---
title: The carbon command
description: Install the carbon CLI, keep it up to date, and see every command it has for sessions, drafts, issues, the browser, sharing and servers.
sidebar:
  order: 1
---

`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](/docs/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:

```bash
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](#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](/docs/cli/servers).

Check what you have:

```bash
carbon --version
```

## Update

```bash
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.

| Flag | What it does |
|---|---|
| `--channel stable` or `--channel beta` | Which releases to take. Beta takes stable releases too. Defaults to the channel this binary came from, so a beta install stays on beta. |
| `--force` | Install the newest release even if it is the one you have. Repairs a damaged binary. |

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

```bash
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

```bash
carbon completion zsh > ~/.zfunc/_carbon
```

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

## Commands

| Command | What it does | Page |
|---|---|---|
| `carbon session` | Start, list, message, rename, stop, settle and set aside sessions | [Sessions](/docs/cli/sessions) |
| `carbon draft` | Save a task for later, list drafts, start or remove one | [Drafts](/docs/cli/drafts) |
| `carbon issue` | Tag a session with the issues its work is against | [Issues](/docs/cli/issues) |
| `carbon browser` | Drive a session's browser: open, read, click, type, screenshot, record | [Browser](/docs/cli/browser) |
| `carbon share` | Publish a session's dev server as a public link | [Share](/docs/cli/share) |
| `carbon server` | Make this machine a Carbon server | [Servers](/docs/cli/servers) |
| `carbon machine` | The list of servers the app connects to | [Servers](/docs/cli/servers) |
| `carbon update` | Install the newest release | above |
| `carbon skill install` | Write the skill for your agents | above |
| `carbon completion` | Print a shell completion script | above |

For how the session commands fit together, see [Orchestration](/docs/cli/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](/docs/cli/orchestration#limits).
- `carbon` never writes to your issue tracker. See [Issues](/docs/cli/issues).