---
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-site.mdick85.workers.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-site.mdick85.workers.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`. |
| `--adopt` | Replace a Worker of that name that this machine did not deploy. This changes its control token. |
| `--url <url>` | Deploy nothing. Use a Worker that another machine deployed. It needs the control token. See [A second machine](https://cf-opencode-site.mdick85.workers.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-site.mdick85.workers.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-site.mdick85.workers.dev/docs/reference/configuration/).

### 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. |
| `--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-site.mdick85.workers.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-site.mdick85.workers.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-site.mdick85.workers.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-site.mdick85.workers.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-site.mdick85.workers.dev/docs/guides/hand-off-a-task/#get-a-message-when-a-task-ends).

### doctor

```text
cf-opencode doctor
```

Check Node, OpenCode, ssh, the saved install, 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.
- `install` and `control token`: both exist.
- `worker`: the Worker accepts the control token and its API version equals the CLI version.
- `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-site.mdick85.workers.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-site.mdick85.workers.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. See [Hand off a task](https://cf-opencode-site.mdick85.workers.dev/docs/guides/hand-off-a-task/).

| Flag | Meaning |
| --- | --- |
| `--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-site.mdick85.workers.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"}`. 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-site.mdick85.workers.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.

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

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

`--reply`, `--wait` and `--follow` need a session ID. 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` and `list_tasks`. 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-site.mdick85.workers.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-site.mdick85.workers.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-site.mdick85.workers.dev/docs/guides/upgrade-and-rebuild/).

## 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-site.mdick85.workers.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-site.mdick85.workers.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-site.mdick85.workers.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-site.mdick85.workers.dev/docs/reference/configuration/). |

Source: https://cf-opencode-site.mdick85.workers.dev/docs/reference/cli/index.mdx
