The carbon command

Install the carbon CLI, keep it up to date, and see every command it has for sessions, drafts, issues, the browser, sharing and servers.

carbon is Carbon’s command line. It lets you, and the agents running inside Carbon, do from a terminal what you would otherwise do in the app: start sessions, list them, message them, save drafts, tag issues, drive a session’s browser, share a dev server, and set up a server. Its main use is letting one agent fan work out into several sessions, each with its own worktree and its own row in the sidebar.

Every command talks to the Carbon app on the same machine, so the app has to be running. On a Linux server, it talks to the Carbon server instead. See Connect a server.

Install

On a Mac, the Carbon app installs carbon for you. Each time it starts, it puts the copy it ships in ~/.local/bin, along with the skill. Agents in Carbon find it there. To run it from your own terminal, add ~/.local/bin to your PATH if it is not on it already.

Anywhere else, install it with:

curl -fsSL https://carbonhq.sh/install.sh | sh

This puts carbon (and carbon-serve, the server) in ~/.local/bin. Set CARBON_INSTALL_DIR to put them somewhere else. If that directory is not on your PATH, the installer says so and prints the line to add.

It also installs the skill that teaches your agents to use carbon. See The skill.

On a machine without the app, a first install goes on to carbon server install, which makes the machine a Carbon server. See Servers.

Check what you have:

carbon --version

Update

carbon update

This finds the newest release and stops if you already have it, so it is safe to run often. Otherwise it installs the new binary over the one you ran, in the same directory, and rewrites the skill.

Leaving beta does not downgrade you: a beta build stays until a stable release is newer than it. To install one exact release, set CARBON_VERSION to its tag, like CARBON_VERSION=cli-v0.12.1 carbon update --force.

On a Mac with the Carbon app, carbon update does nothing and says so. The CLI comes with the app, so updating the app updates it.

If a background server is installed on this machine, carbon update does not restart it, since that stops every running agent. It prints the command that does.

How it reaches the app

Every command connects to a socket in ~/.carbon: ~/.carbon/carbon.sock. Nothing on the network can reach it. Set CARBON_ENDPOINT to a socket path to talk to a different one.

Sessions Carbon starts get two things in their environment: CARBON_SESSION_ID, naming the session, and CARBON_ENDPOINT, naming the app that started it. That is how carbon knows which session is calling. From inside a session, a new session is nested under the caller, and carbon browser drives the caller’s own browser. From your own terminal there is no calling session, so commands that need one take --session <id>.

The skill

carbon skill install

Writes the skill to:

• ~/.claude/skills/carbon/SKILL.md, for Claude Code
• ~/.codex/skills/carbon/SKILL.md, for Codex
• ~/.agents/skills/carbon/SKILL.md, for pi

The skill is built into the binary, so it always describes the carbon you have. The installer and carbon update both run carbon skill install, so you only need it by hand if a skill file was deleted.

Shell completion

carbon completion zsh > ~/.zfunc/_carbon

Prints a completion script for bash, zsh, fish, elvish or powershell.

Commands

For how the session commands fit together, see Orchestration.

A command group run on its own, like carbon session, prints its help. Every command takes --help.

Older spellings still work, so scripts and agents with an older skill keep running: carbon new, carbon ls and carbon send are carbon session new, ls and send; carbon setup is carbon server install; carbon serve is carbon server run; carbon share <port> is carbon share start <port>.

Output and exit codes

Commands that make something print its id alone on standard output, and a sentence for you on standard error. So id=$(carbon session new "…") captures the id.

A failure prints carbon: <reason> and exits with 1. A command typed wrong exits with 2 and prints usage.

When the app and the CLI disagree

The app and the CLI ship separately, so they can drift apart. When the two speak different versions, the app refuses the command and the message names which side is behind:

• “this carbon CLI speaks protocol vN, the app speaks vM — run `carbon update`” means the CLI is behind. Run carbon update and try again.
• “… — update the Carbon app” means the app is behind. Update the app.

Nothing was created or sent, so retrying after the fix is safe. Updating the app first is the smoother order: the app’s next launch updates the CLI too.

When it cannot reach the app

Three messages, and only the second means the app is closed:

• permission denied reaching Carbon at … — the app may well be running. A sandbox, or the permissions on the socket’s path, blocked the connection. If the command ran inside a sandbox, run it again with that sandbox lifted for this one command.
• Carbon isn't running. Start the app and try again. — the app is closed. Open it.
• could not connect to Carbon at … — something else went wrong, and the line says what. It says nothing about whether the app is up.

Limits

• carbon needs the app, or a Carbon server, running on the same machine. It does not reach a remote server.
• You cannot read another session’s transcript from the CLI. See Orchestration.
• carbon never writes to your issue tracker. See Issues.