---
title: "CLI reference"
description: "Every cf-opencode command and flag, with the default values and the output formats."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-opencode.system3inference.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

```text
cf-opencode <command> [options]
```

Run `cf-opencode --help` for the command list. Run `cf-opencode <command> --help` for the options of one command.

In the tables, `<workspace>` is a workspace ID. `connect` makes the ID from the name of the directory. A workspace ID has letters, digits, `_` and `-`, starts with a letter or digit, and has at most 128 characters.

## Global options

| Option | Meaning |
| --- | --- |
| `--url <url>` | The Worker URL. The default is `~/.cf-opencode/install.json`, or `CF_OPENCODE_URL`. |
| `--json` | Print one JSON document on stdout. Progress stays on stderr. |
| `-h`, `--help` | Show help for the command. |
| `-v`, `--version` | Print the CLI version. |

With `--json`, an error from a command is `{"ok":false,"error":"Failed: … — fix: …"}` on stdout. Without it, the error is on stderr. An unknown command or a bad flag is always on stderr.

The exit code is 0 on success, 1 on failure and 2 on a usage error such as an unknown command or flag.

When the Worker refuses the control token, the CLI prints `Failed: the Worker refused the control token on this machine — fix: …`. The Worker itself answers a request without a valid control token with one bare `401 {"error":"Unauthorized"}` for every path.

## Set up

### init

```text
cf-opencode init
```

Check this machine and your Cloudflare account, deploy the Worker and the workspace image, and save the install. See [Quickstart](https://cf-opencode.system3inference.dev/docs/quickstart/).

| Flag | Meaning |
| --- | --- |
| `--account <id>` | The account to use, when the login sees more than one. You can set `CLOUDFLARE_ACCOUNT_ID` instead. |
| `--name <name>` | The Worker name. The default is `cf-opencode`. Use lowercase letters, digits and `-`, up to 63 characters. |
| `--token-file <path>` | A file with a Cloudflare API token. The default is `CLOUDFLARE_API_TOKEN`, then the `wrangler login`. |
| `--domain <hostname>` | Also put the Worker on this hostname, as a Custom Domain. The install URL is then `https://<hostname>`. The zone of the hostname must be in the account. See [Use your own hostname](#use-your-own-hostname). |
| `--adopt` | Replace a Worker of that name that this machine did not deploy. This changes its control token. With `--domain`, also replace DNS records on the hostname, or take the hostname from another Worker. |
| `--url <url>` | Deploy nothing. Use a Worker that is deployed, from another machine or at a new URL. Any `https` URL works. It needs the control token. See [A second machine](https://cf-opencode.system3inference.dev/docs/guides/second-machine/). |
| `--yes`, `-y` | Never prompt. `--json` and a non-terminal stdin also imply it. |
| `--no-github` | Do not set up GitHub now. Later, run `cf-opencode git-token`. |
| `--no-skill` | Do not install the handoff skill for Claude Code and OpenCode on this machine. |

`init` has these steps: check the machine and the account, deploy, store the control token, set up GitHub, and install the handoff skill. The skill step installs the skill for each agent whose config folder exists on this machine. On a terminal, it asks first. It never replaces a skill file that differs. See [Hand off a task](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#the-handoff-skill-for-agents).

`init` reads your settings from `~/.cf-opencode/config.json` and prints the keys it found. See [Configuration](https://cf-opencode.system3inference.dev/docs/reference/configuration/).

#### Use your own hostname

```sh
cf-opencode init --domain code.example.com
```

`init` writes the hostname into the copied `wrangler.jsonc` as a route with `custom_domain: true`. `wrangler deploy` then makes the Custom Domain and its DNS record. The workers.dev URL stays on, so machines that use it keep working.

Before the deploy, `init` reads the account and changes nothing. It fails with one `Failed:` line when:

- the account has no zone for the hostname, or the zone is not active.
- the hostname has DNS records. The deploy would replace them.
- the hostname is a Custom Domain of another Worker.

Pass `--adopt` to replace the records or take the hostname. An API token needs Workers Routes Write on the zone too.

A new Custom Domain can take some minutes to answer. `init` checks the deploy on the workers.dev URL. If the hostname does not answer yet, `init` prints a `!` line and saves the install. Run `cf-opencode doctor` later.

`install.json` keeps the hostname, so `upgrade` deploys it again. A rerun of `init` without `--domain` also keeps it.

#### After the Worker URL changed

When the account's workers.dev subdomain changes, the saved URL stops working. Save the new URL. Nothing is deployed:

```sh
cf-opencode init --url https://cf-opencode.<new subdomain>.workers.dev
```

`cf-opencode doctor` prints this command with the right URL when it finds the Worker at a new URL. `init --url` keeps the account and the Custom Domain of the saved install, so `upgrade` still works.

### upgrade

```text
cf-opencode upgrade
```

Redeploy the Worker and the image from this CLI version. The control token stays.

| Flag | Meaning |
| --- | --- |
| `--token-file <path>` | A file with a Cloudflare API token. |
| `--domain <hostname>` | Put the Worker on this hostname. The default is the saved hostname. |
| `--adopt` | With `--domain`, replace DNS records on the hostname, or take it from another Worker. |
| `--yes`, `-y` | Never prompt. |
| `--no-github` | Accepted. Skips the GitHub step. |
| `--no-skill` | Accepted. Skips the handoff skill step. |

`upgrade` fails with `nothing to upgrade on this machine` if no install is saved.

### uninstall

```text
cf-opencode uninstall [--yes]
```

List the Worker, its container app and its image tags. With `--yes`, delete them. See [Uninstall](https://cf-opencode.system3inference.dev/docs/guides/uninstall/).

| Flag | Meaning |
| --- | --- |
| `--yes`, `-y` | Delete. Without it, the command is a dry run. |
| `--token-file <path>` | A file with a Cloudflare API token. |

### git-token

```text
cf-opencode git-token [--remove]
```

Let workspaces use GitHub. The command reads the token from stdin, or asks for it on a terminal without echo. It never takes the token as an argument. See [GitHub and private repositories](https://cf-opencode.system3inference.dev/docs/guides/github/).

| Flag | Meaning |
| --- | --- |
| `--remove` | Delete the token from the Worker. |
| `--token-file <path>` | A file with a Cloudflare API token. The default is the `wrangler login` or `CLOUDFLARE_API_TOKEN`. |

### skill

```text
cf-opencode skill [--install --claude | --install --opencode | --install --dir <path>] [--force]
```

Print the path and the text of the handoff skill. The skill tells a local agent when and how to hand off a task. See [Hand off a task](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#the-handoff-skill-for-agents).

| Flag | Meaning |
| --- | --- |
| `--install --claude` | Copy the skill to `~/.claude/skills/cf-opencode-handoff/`. |
| `--install --opencode` | Copy the skill to `~/.config/opencode/skills/cf-opencode-handoff/`. |
| `--install --dir <path>` | Copy the skill to `<path>/cf-opencode-handoff/`. |
| `--force` | Replace a `SKILL.md` there that differs. Without it, the command fails and changes nothing. |

### notify-url

```text
cf-opencode notify-url [--remove]
```

Set where the Worker sends a task's result and the workspace's notes. The command reads the URL from stdin, or asks for it on a terminal without echo. It never takes the URL as an argument. It stores the URL as the Worker secret `NOTIFY_URL`. The URL must be `https`, with no user or password in it, to a public host name. Running workspaces use it at once. See [Get a message when a task ends](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#get-a-message-when-a-task-ends).

| Flag | Meaning |
| --- | --- |
| `--remove` | Delete the URL from the Worker. |
| `--token-file <path>` | A file with a Cloudflare API token. The default is the `wrangler login` or `CLOUDFLARE_API_TOKEN`. |

### notify-key

```text
cf-opencode notify-key
```

Print the key that signs the `POST` requests to the notify URL. The receiver checks `x-cf-opencode-signature: sha256=<hex HMAC-SHA256 of "<x-cf-opencode-timestamp>.<body>">` with this key, and refuses a timestamp more than 5 minutes old. The key comes from the control token. Keep it secret. See [Get a message when a task ends](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#get-a-message-when-a-task-ends).

### doctor

```text
cf-opencode doctor
```

Check Node, OpenCode, ssh, the Worker URL, the control token, the Worker and its bindings. `doctor` never starts a workspace. It checks:

- `node`: version 22 or newer.
- `opencode`: installed, and version 2.
- `ssh`: a client exists. Only `ssh`, `ssh-config` and herdr need it.
- `url`: the Worker URL in use, and where it comes from: `--url`, `CF_OPENCODE_URL` or `~/.cf-opencode/install.json`. The line also names the Worker and its Custom Domain.
- `control token`: it exists.
- `worker`: the Worker at that URL accepts the control token, and its API version equals the CLI version. When the URL does not answer, `doctor` looks for the Worker in the account. If the Worker answers at its workers.dev URL now, the fix is `cf-opencode init --url <that URL>`. This step reads the account with your `wrangler` login and changes nothing.
- `models`, `browse` and `github`: the AI binding, the Browser Run binding and the GitHub token.
- `notify`: whether a notify URL is set. It is optional. `doctor` never prints the URL.

Each line starts with `✓`, `!` or `✗`. The exit code is 1 if any line is `✗`.

### completion

```text
cf-opencode completion <bash|zsh|fish>
```

Print a tab-completion script for commands, flags and workspace IDs. The script asks the CLI for the words, so it stays correct after an upgrade.

| Shell | Setup |
| --- | --- |
| `bash` | Add `eval "$(cf-opencode completion bash)"` to `~/.bashrc`. |
| `zsh` | Add `eval "$(cf-opencode completion zsh)"` to `~/.zshrc`. |
| `fish` | Run `cf-opencode completion fish > ~/.config/fish/completions/cf-opencode.fish`. |

The completion offers only plain words. Workspace IDs come from `~/.cf-opencode/workspaces`.

## Workspaces

### connect

```text
cf-opencode connect [workspace]
```

Wake or create a workspace and open it in your local OpenCode. Without an ID, `connect` makes one from the name of the current directory: lowercase, with each other character changed to `-`.

| Flag | Meaning |
| --- | --- |
| `--dir <path>` | The project directory inside the workspace. The default is `/home/user/project`. |
| `--repo <url>` | The git remote to clone when the workspace has no snapshot yet. The default is the `origin` remote of the current directory. |
| `--branch <name>` | The branch to check out. The default is the current branch. |
| `--no-attach` | Do not open OpenCode. Print one JSON object with the workspace and its server URL. |
| `--skills <a,b\|all>` | Copy these skills from this machine into the workspace before OpenCode opens. Off by default. See [`skills`](#skills) and [Skills in a workspace](https://cf-opencode.system3inference.dev/docs/guides/skills/). |
| `--continue`, `-c` | Open the last session of the workspace. |
| `--session <id>`, `-s <id>` | Open that session. Use the `ses_…` ID that OpenCode prints on exit. |
| `--url <url>` | The Worker URL. |

With `--no-attach` or `--json`, stdout is `{"ok":true,"workspace":"…","url":"…","username":"opencode"}`.

### sessions

```text
cf-opencode sessions [workspace]
```

List OpenCode sessions across your workspaces, newest first. The command wakes nothing. See [Sessions](https://cf-opencode.system3inference.dev/docs/concepts/sessions/).

### run

```text
cf-opencode run "<task>" [workspace]
```

Give a task to OpenCode in the workspace of the current checkout, and return. The task runs as a new session in the workspace. `run` fails when the branch is not pushed or files have changes that are not committed. One task at a time uses the checkout of a workspace: `run` fails when a task there is `running` or `waiting`. See [Hand off a task](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/).

| Flag | Meaning |
| --- | --- |
| `--branch <name>` | Start from this branch as it is on `origin`. The default is the branch of the checkout. The preflight then checks only that `origin` has the branch. |
| `--worktree` | Start the task in a new git worktree in the workspace, so it does not share the checkout with another task. |
| `--new` | Start the task in a new workspace, named `<checkout>-<short id>`. It pauses when idle. `maxRunning` counts it. Not with `--worktree` or a workspace argument. |
| `--auto` | The agent runs with no permission prompts. A deny rule still applies. The default is off. |
| `--title <text>` | The session title. The default comes from the task. |
| `--model <provider/model>` | The model of the session. The default is the model of the workspace. |
| `--allow-dirty` | Start anyway. Print what the workspace will not see. |
| `--skills <a,b\|all>` | Copy these skills from this machine into the workspace before the task starts. See [Skills in a workspace](https://cf-opencode.system3inference.dev/docs/guides/skills/). |
| `--schema <file.json>` | The last message must end with a `json` block that matches this JSON Schema. The result then has `structured`. Only `type`, `properties`, `required`, `items`, `enum` and `additionalProperties: false` are allowed. |
| `--wait` | Wait until the task is not `running`, then print the result. |
| `--follow` | As `--wait`, and show the agent's tool calls and messages while it works. |
| `--timeout <minutes>` | How long `--wait` and `--follow` wait. The default is 60. |

`--wait` and `--follow` do not go together. With `--json`, stdout is `{"ok":true,"workspace":"…","session":"ses_…","title":"…","state":"running"}`, plus `newWorkspace`, `worktree` and `auto` when they apply. With `--wait --json`, stdout is the result record. With `--follow --json`, stdout is one JSON object for each event, one per line, then the result record. With `--wait` or `--follow`, the exit code is 0 for `done`, 1 for `failed`, 2 for `waiting`, 3 for a timeout and 4 for `stopped`. See [Hand off a task](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#output-for-agents).

### tasks

```text
cf-opencode tasks [workspace | session]
```

List the tasks that `run` started. Tasks that ended and that you did not read come first, marked `*`. Then the newest come first. The columns are `WORKSPACE`, `SESSION`, `STATE`, `AGE` and `TITLE`. With a `ses_…` ID, show one task: its state, summary, branch, commits and pull request. This marks the task read. The command wakes nothing.

The states are `running`, `done`, `failed`, `waiting` and `stopped`. `stopped` means that the workspace paused while the task ran. A task whose agent ended its turn while a long job (`cf-opencode-job`) runs is `running`. The list shows it as `running, job`, and `tasks <ses_…>` shows each job in a `Job` line.

| Flag | Meaning |
| --- | --- |
| `--workspace <id>` | The workspace of the task. The default is the workspace that has the task. |
| `--unseen` | List only the tasks that ended and that you did not read. |
| `--reply "<text>"` | With a session ID: send one more message to the session, for example the answer to its question. It wakes a paused workspace. With `--wait` or `--follow`, the command then watches the task. A permission request is not answered this way: use `cf-opencode connect <workspace> --session <ses_…>`. |
| `--wait` | With a session ID: wait until the task is not `running`. The exit codes are the same as for `run --wait`. |
| `--follow` | With a session ID: as `--wait`, and show the agent's progress live. |
| `--timeout <minutes>` | How long `--wait` and `--follow` wait. The default is 60. |
| `--pull` | With a session ID: fetch the task's branch from `origin` into the checkout in the current directory, and make or fast-forward a local branch that tracks it. Your files and your checked-out branch do not change, except a fast-forward of that branch when it has no changes. It fails when the task has no pushed branch or has `unpushed` commits. |

A task that ends with commits that are not pushed or processes left running gets one automatic reply from the Worker. The task stays `running` until that turn ends. `tasks <ses_…>` shows the reply in the line `Auto reply`. See [The automatic reply](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#the-automatic-reply).

With a session ID and `--json`, stdout is the result record. With `--pull --json`, stdout is `{"ok":true,"workspace":"…","session":"ses_…","branch":"…","commit":"…","local":"created","checkedOut":false}`. With `--reply --json` and no `--wait` or `--follow`, stdout is `{"ok":true,"workspace":"…","session":"ses_…","replied":true}`.

`--reply`, `--wait`, `--follow` and `--pull` need a session ID. `--pull` goes alone. The exit codes of `--wait` and `--follow` are 0 for `done`, 1 for `failed`, 2 for `waiting`, 3 for a timeout and 4 for `stopped`.

### mcp

```text
cf-opencode mcp
```

Serve `run` and `tasks` to an agent as MCP tools over stdio: `handoff_task`, `get_task`, `wait_task`, `list_tasks` and `pull_task`. stdout carries MCP messages only. Logs go to stderr. The tools use the install and the control token of this machine. `handoff_task` works on the directory that the client started the server in, or on its `directory` argument. The `directory` argument must be that folder or a folder under it. See [Hand off tasks over MCP](https://cf-opencode.system3inference.dev/docs/guides/mcp/).

To add the server, run `claude mcp add cf-opencode -- cf-opencode mcp` for Claude Code. For other clients, add a stdio server with the command `cf-opencode mcp`.

### skills

```text
cf-opencode skills [push|remove|default] [name...]
```

Copy skills from this machine into a workspace, so the remote agent has them. A skill is a folder with a `SKILL.md`. Nothing is copied unless you ask. See [Skills in a workspace](https://cf-opencode.system3inference.dev/docs/guides/skills/).

| Command | Meaning |
| --- | --- |
| `cf-opencode skills` | List the skills on this machine, and which of them are in the workspace. It needs no running workspace. |
| `cf-opencode skills push <name...>` | Copy the named skills. A copy that is already there is replaced. |
| `cf-opencode skills push --all` | Copy every skill found on this machine. |
| `cf-opencode skills push` | With no names: copy the saved default list. |
| `cf-opencode skills remove <name...>` | Delete the named skills from the workspace. |
| `cf-opencode skills default <name...>` | Save a list. Every new workspace gets these skills on its first connect. |
| `cf-opencode skills default --none` | Clear the saved list. This is the start state. |

| Flag | Meaning |
| --- | --- |
| `--workspace <id>` | The workspace. The default is the workspace of the current directory. |
| `--from <dir>` | A skills folder to read. The default is `~/.config/opencode/skills`, `~/.claude/skills` and `~/.agents/skills`. |
| `--all` | With `push` or `default`: every skill found. |
| `--none` | With `default`: clear the list. |

The copies go to `~/.config/opencode/skills` in the workspace. They stay on its disk and in its snapshots. `.git`, `node_modules`, `.env`, `.env.*`, `*.pem`, `*.key` and `.DS_Store` are not copied. A link inside a skill is not followed. A skill over 5 MB is refused. `push` and `remove` need `ssh` on this machine.

### list

```text
cf-opencode list
```

List the workspaces this machine connected to. The columns are `WORKSPACE`, `STATE`, `SINCE`, `SNAPSHOT EXPIRES` and `REPO`. A `!` after an expiry means the snapshot expires in less than 2 days.

### status

```text
cf-opencode status [workspace]
```

Show one workspace, or the install when you give no ID. For a workspace it shows the state, directory, awake time or stop time, whether the image is older than the deployed one, and the snapshot expiry.

### logs

```text
cf-opencode logs <workspace>
```

Print the redacted `opencode serve` log.

| Flag | Meaning |
| --- | --- |
| `--lines <n>` | The number of lines. The default is 100. |

### pause

```text
cf-opencode pause <workspace>
```

Save the disk and stop the workspace. If this machine connected to the workspace, the container stops at once.

### delete

```text
cf-opencode delete <workspace>
```

Destroy the workspace. The Worker forgets its disk snapshot and its project snapshot. The next `connect` starts from the image. Cloudflare drops the old snapshot data on its own. The command also removes the local files for the workspace.

### rebuild

```text
cf-opencode rebuild <workspace>
```

Move a workspace onto the deployed image. It keeps `/home/user`. It stops the agent. See [Upgrade and rebuild](https://cf-opencode.system3inference.dev/docs/guides/upgrade-and-rebuild/).

### cp

```text
cf-opencode cp <from> <to>
```

Copy a file or a folder. A side is `<workspace>:<path>` or a local path. At least one side is a workspace. A workspace path is relative to the checkout, or starts with `/` or `~` inside `/home/user`. See [Move a file between workspaces](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#move-a-file-between-workspaces).

```sh
cf-opencode cp app:export.json.gz api:data/   # workspace to workspace
cf-opencode cp app:build ./build              # workspace to this machine
cf-opencode cp ./fixtures app:test/           # this machine to a workspace
```

An existing folder, or a path that ends in `/`, takes the item inside it. A paused workspace wakes, and pauses again when it is idle. The target changes only when the copy ends without an error.

| Flag | Meaning |
| --- | --- |
| `--force` | Replace a target that exists. Without it, `cp` refuses. |
| `--json` | One JSON document with `from`, `to`, `bytes`, `files`, `dirs`, `links` and `seconds`. |

Limits: 4 GB and 200,000 entries in one copy, 30 minutes in each workspace, and 100 MB for a copy from this machine.

With the store on (`store`), a side can be `store:<name>`. `store:` alone takes the name of the source. The store holds files, not folders.

### store

```text
cf-opencode store [rm <name>...]
```

List the files in the store, with size and age, or remove files. The store is off unless `store` is `true`. See [Share files through the store](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#through-the-store).

| Flag | Meaning |
| --- | --- |
| `--prefix <text>` | List only the names that start with the text. |
| `--json` | One JSON document with the list. |

## Terminal

### shell

```text
cf-opencode shell <workspace>
```

Open a terminal in the workspace, inside tmux. Closing it does not stop what runs there.

| Flag | Meaning |
| --- | --- |
| `--session <name>` | The tmux session to attach or create. The default is `main`. |

### ssh

```text
cf-opencode ssh <workspace> [-- ssh args]
```

SSH into the workspace as `user`, over the Worker. It needs the system `ssh`.

### ssh-config

```text
cf-opencode ssh-config <workspace>
```

Print a `~/.ssh/config` Host block. The host name is `cf-opencode-<workspace>`. See [Shell and SSH](https://cf-opencode.system3inference.dev/docs/guides/shell-and-ssh/).

### ssh-proxy

```text
cf-opencode ssh-proxy <workspace>
```

The `ProxyCommand` that `ssh` and `ssh-config` use. You do not run it yourself.

## Browser

### browse

```text
cf-opencode browse <workspace>
```

Open a Browser Run session for a workspace. Print its websocket address. See [Browsing](https://cf-opencode.system3inference.dev/docs/guides/browsing/).

### preview

```text
cf-opencode preview [workspace] <port...>
```

Open a dev server that runs in the workspace at `http://localhost:<port>` on this machine. The default is a private forward over the workspace's SSH. Nothing is public. The forward lives while the command runs. Ctrl-C stops it. Without a workspace, the command uses the workspace of the current directory. You can give more than one port. See [Preview a dev server](https://cf-opencode.system3inference.dev/docs/guides/preview/).

```text
cf-opencode preview 3000
cf-opencode preview app 3000 5173
```

| Flag | Meaning |
| --- | --- |
| `--no-open` | Do not open the browser. |
| `--web` | Use a URL on the Worker, behind a one-time sign-in link. It needs no `ssh` here. The dev server must listen on `0.0.0.0`. An app with absolute paths needs a base path. |
| `--public` | Make a URL that needs no password, until `--stop`. It needs the control token. |
| `--stop` | Remove the public URL of `<port>`, or of every port when you give no port. |
| `--list` | List the public URLs of the workspace. |

`--web`, `--public`, `--stop`, `--list` and `--json` use the Worker, not the forward. With `--json`, the command prints one JSON document. `--public`, `--stop` and `--list` do not go together.

## Environment variables

| Variable | Used for |
| --- | --- |
| `CF_OPENCODE_URL` | The Worker URL, when `--url` is not set. |
| `CF_OPENCODE_CONTROL_TOKEN` | The control token, when `~/.cf-opencode/control-token` does not exist. |
| `CLOUDFLARE_API_TOKEN` | A Cloudflare API token for `init`, `upgrade`, `uninstall` and `git-token`. |
| `CLOUDFLARE_ACCOUNT_ID` | The account for `init`. |
| `CF_OPENCODE_CONFIG` | Not read by the CLI. It is a Worker variable. See [Configuration](https://cf-opencode.system3inference.dev/docs/reference/configuration/). |

Source: https://cf-opencode.system3inference.dev/docs/reference/cli/index.mdx
