CLI

The sixteenbridges command: bubbles from a terminal, for people and for AI agents. Node.js 20 or newer, nothing else.

Install

Run it with npx, nothing to install first:

Terminal

npx sixteenbridges --help

Or install it once, for the shorter command:

Terminal

npm install -g sixteenbridges
sixteenbridges --help

Once per computer. Your browser opens sixteenbridges.com; you sign in and click Allow; the terminal is connected.

Terminal

npx sixteenbridges login
# Opening your browser to sign in…
# Signed in as you@example.com.

Behind it: the command registers this computer as an app (it shows as "Sixteen Bridges CLI on your computer" on your account page), sends the browser to sign in with PKCE, and takes the answer on http://127.0.0.1. It waits up to 5 minutes for the click.

No browser on this computer (SSH, a container)

The link opens on any device; sixteenbridges.com then shows a code to paste back. Chosen by itself over SSH.

Terminal

npx sixteenbridges login --no-browser
# Open this link, sign in and click Allow:  https://…
# Then paste the code it shows here: ▍

Two steps, for an agent that can't keep a command running

Terminal

npx sixteenbridges login --no-wait
# prints the link and exits; the person opens it and clicks Allow

npx sixteenbridges login --code "<the code sixteenbridges.com shows>"
# within 15 minutes

Check, and sign out

Terminal

npx sixteenbridges whoami
npx sixteenbridges logout

For AI agents

Tell the agent: "Use the sixteenbridges command for my bubbles." Its --help is written for it. An agent that finds it isn't signed in (exit code 3) runs login itself: the person only clicks Allow.

Terminal

npx -y sixteenbridges whoami || npx -y sixteenbridges login
npx -y sixteenbridges list
npx -y sixteenbridges save "Release notes" notes.md --source claude --label "Claude Code"

Show bubbles to the person as a short list, read only the ones needed, and ask before deleting. Desktop apps (Claude Desktop, Cursor, VS Code) can run sixteenbridges mcp as a local MCP server instead: MCP, locally.

Commands

Command	Does
`list [--limit N] [--cursor C]`	Your bubbles, newest first: id, title, source, size, date, a one-line preview.
`search <words…>`	Bubbles whose title or content contains the words.
`get <id> [--raw] [--offset N]`	One bubble. Long ones come in pages; --raw prints the exact text.
`save <title> [file\|-]`	A new bubble from a file, a pipe, or --content. --source and --label say where it came from.
`update <id>`	--title, --content or --file to replace, --append to add to the end.
`delete <id>`	To the trash for 7 days.
`trash`	What is in the trash.
`restore <id>`	Back from the trash.
`share <id…> --to <email>`	Copies of up to 20 bubbles into another account: all of them, or none if their plan is full.
`shares [--sent \| --received]`	What you shared and were shared, newest first, with which received ones are new.
`mcp`	A local MCP server on stdin and stdout.
`whoami · login · logout`	Who this computer is signed in as; sign it in or out.

Terminal

sixteenbridges save plan.md                       # the file's name becomes the title
cat chat.md | sixteenbridges save "Lisbon chat"    # from a pipe
sixteenbridges get bub_0195f3a2-… --raw > plan.md  # the exact text, byte for byte
sixteenbridges update bub_0195f3a2-… --append "Decided: ship Friday."

JSON output

Every command takes --json and prints the API's own payload. Errors are then one JSON line on stderr.

Terminal

sixteenbridges list --json | jq '.bubbles[].title'
sixteenbridges get bub_0195f3a2-… --json | jq -r .content

Exit codes

Code	Means	Do
0	Done
1	Refused: not found, the plan's limit, too large, bad input	Read the message: it says what to do.
2	Wrong usage	Read the command's --help.
3	Not signed in, or this computer was disconnected	Run login.
4	Sixteen Bridges is unavailable	Try again in a minute.

Where the sign-in lives

~/.config/sixteenbridges/credentials.json (or $XDG_CONFIG_HOME, or %APPDATA%\sixteenbridges on Windows), readable by you only. Tokens renew by themselves, and several commands at once are safe: one renews, the others wait for it. The command never prints a token.

Environment

Variable	For
`SIXTEENBRIDGES_CONFIG_DIR`	Keep a separate sign-in, for a second account.
`BROWSER`	The browser to open; none never opens one.