Symbol CLI

What It IsCopy Anchor Link

The Symbol CLI is a command named symbol for working with your capsules from a terminal. It lists, reads and searches capsules, reads a Type's guidance, and creates and edits capsules and log entries. It works the same for a person typing commands and for an agent running them, and the server applies the same write rules to it as to the Symbol MCP: guidance first, valid field values, and only the scopes you approved.

It talks to whichever Symbol server you point it at, including a local development server, and it has no built-in server, so it never writes to production unless you choose it.

Running It From the RepositoryCopy Anchor Link

The CLI needs Node.js 20.19 or later and nothing else: it has no third-party dependencies.

# From the repository root
node packages/cli/bin/symbol.mjs --help

# Or, after npm ci at the root, through the workspace bin
npx symbol --help

The rest of this page writes symbol for either form.

Choosing a ServerCopy Anchor Link

Every command talks to one server, chosen in this order:

1. --server <name|url> on the command
2. the SYMBOL_SERVER environment variable
3. the default saved by symbol server use

With none of these, the command stops with exit code 2 and tells you how to pick one.

A server URL must use https://. Plain http:// is accepted only for localhost, names ending in .localhost, 127.0.0.1 and [::1], because a token sent over plain http to another machine can be read on the way.

Signing InCopy Anchor Link

symbol login --server https://symbol.chat

symbol whoami

account: ana@example.com
server: https://symbol.chat
credential: oauth
scopes: read create update
connected app: Symbol CLI (on "ana-laptop")

symbol login flags:

The first successful sign-in also saves that server as your default.

Each sign-in is its own entry under Settings → Connected Apps, named after the device, for example "Symbol CLI (on "ana-laptop")", with its own Last used date and request count. symbol login and symbol whoami print that entry name, so you can tell which entry belongs to which machine. Each sign-in keeps only the workspaces you approved for it, whatever you approve for another one.

The device name defaults to this machine's hostname. It is shown in your Connected Apps and to Symbol support. Pass --device-name to choose another.

Revoking an entry signs out that sign-in alone, and symbol logout removes its own entry. Signing in again in the same CLI home, for the same server, replaces the earlier sign-in, so one machine keeps one entry.

With an API keyCopy Anchor Link

For CI or an agent that already holds a key, pipe the key in on stdin. The CLI never takes a key as a command argument, where it would land in your shell history.

symbol login --with-token --server https://symbol.chat < key.txt

You can also set SYMBOL_TOKEN in the environment. It overrides the stored sign-in for that run and is never written to disk.

Signing outCopy Anchor Link

symbol logout

symbol logout revokes the stored tokens on the server and forgets them. If the server cannot be reached, the CLI still forgets them and exits 1, warning that the token may stay live until it expires. For a stored API key, logout only forgets it: the key stays valid until you revoke it in Settings.

The CLI keeps its files in ~/.symbol/cli (config.json, credentials.json and state.json). The credentials and state files are readable only by your user. Set SYMBOL_CLI_HOME to use a different directory.

CommandsCopy Anchor Link

Every command accepts these global flags:

symbol --help lists every command, and symbol <command> --help lists every flag of that command.

WorkspacesCopy Anchor Link

symbol workspace list

--workspace takes personal, a workspace id, or the workspace's exact name (letter case does not matter). A partial name such as Acme for "Acme Research" is refused with exit 2 and the list of your real workspaces, so a write never lands in a workspace you did not mean.

TypesCopy Anchor Link

symbol type list
symbol type show notes

symbol type list lists your Types. symbol type show <type> prints a Type's guidance and its fields, and remembers the guidance token that writes to that Type need (see Write Rules below). A Type can be named by its slug, its exact name, or its id.

Listing and reading capsulesCopy Anchor Link

symbol capsule list --type notes --limit 20
symbol capsule list --collection reading --cursor <cursor>
symbol capsule get @notes/3
symbol capsule get @notes/launch-plan

symbol capsule list flags:

symbol capsule get takes @type/3, @type/<alias> or a capsule id, and prints the title, reference, Type, field values and body.

SearchingCopy Anchor Link

symbol search "launch plan"
symbol search budget --type notes --sort newest

symbol search returns the same capsules in the same order as the search page in the web app.

Creating a capsuleCopy Anchor Link

symbol type show notes
symbol capsule create --type notes --title "Launch plan" \
  --summary "What ships on Friday and who owns it." \
  --content-file plan.md --field status=draft --tag launch

--field values are read by the Type's field schema: numbers and true or false become numbers and booleans, and a value that starts with [ or { is read as JSON, for lists. The server checks every value and refuses invalid ones with its own message.

Editing a capsuleCopy Anchor Link

symbol capsule edit @notes/3 --replace "Friday" --with "Monday" \
  --summary "Launch moved to Monday."
symbol capsule edit @notes/3 --field status=final

symbol capsule edit reads the capsule fresh before writing, and the server refuses the write if someone else changed the capsule in between. If any --replace text is missing or appears more than once, nothing is written.

Appending to a logCopy Anchor Link

symbol type show standup
symbol log append --type standup --field mood=good --field hours=6
symbol log append @projects/atlas --field note="Shipped the beta"

symbol log append takes an owner capsule (a capsule whose Type keeps a log) or --type <log type> for a dated log. An entry is its field values: there is no body.

Write RulesCopy Anchor Link

The CLI declares itself to the server as an assistant client, so the server applies the same rules as for the Symbol MCP, for people and agents alike:

• Read the Type first. Run symbol type show <type> before writing to a Type that has guidance. The CLI remembers the guidance token it returns and sends it with capsule create, capsule edit and log append. Without it, the server refuses the write and the CLI adds a line telling you which command to run.
• Field values are checked against the Type's fields.
• Scopes apply. A sign-in approved for read only cannot write.
• A summary is expected when a body changes.

The CLI never decides these on its own: it relays the server's answer, with the same reason the MCP gets.

Encrypted CapsulesCopy Anchor Link

The CLI cannot decrypt end-to-end encrypted capsules. symbol capsule get on one stops with exit code 1 and the message "This capsule is end-to-end encrypted. The CLI cannot decrypt it. Open it in the web app or in Symbol Bridge." In lists and search results, an encrypted capsule appears with its title and "encrypted": true, never with its encrypted body.

To read encrypted capsules from an assistant, use Symbol Bridge.

JSON OutputCopy Anchor Link

With --json, a command writes exactly one JSON document to stdout: the server's response for data commands, or a small object for local commands such as symbol server list. Errors go to stderr as one JSON object:

{"error":{"code":"guidance_token_required","message":"...","status":422}}

Without --json, errors read error: <reason> (<code>, HTTP <status>). Either way, a failed command writes nothing to stdout, so a pipe never receives half a result.

Exit CodesCopy Anchor Link

When a sign-in expires, the CLI renews it once on its own. If the server refuses the renewal (for example because you revoked the grant in Connected Apps), the CLI forgets the sign-in and exits 4 with Signed out: run "symbol login".

If the server warns that this version of the API is being retired, the CLI prints one warning naming the date. If the server no longer serves it, commands exit 1 asking you to update the CLI.