Skip to content

CLI reference

Every cf-opencode command and flag, with the default values and the output formats.

Updated
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

cf-opencode init

Check this machine and your Cloudflare account, deploy the Worker and the workspace image, and save the install. See 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.
--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.

init reads your settings from ~/.cf-opencode/config.json and prints the keys it found. See Configuration.

upgrade

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

cf-opencode uninstall [--yes]

List the Worker, its container app and its image tags. With --yes, delete them. See 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

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.

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

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.

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

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.

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

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.

doctor

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

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

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 and Skills in a workspace.
--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

cf-opencode sessions [workspace]

List OpenCode sessions across your workspaces, newest first. The command wakes nothing. See Sessions.

run

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.

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

tasks

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

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.

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

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.

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

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

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

cf-opencode logs <workspace>

Print the redacted opencode serve log.

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

pause

cf-opencode pause <workspace>

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

delete

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

cf-opencode rebuild <workspace>

Move a workspace onto the deployed image. It keeps /home/user. It stops the agent. See Upgrade and rebuild.

Terminal

shell

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

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

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

ssh-config

cf-opencode ssh-config <workspace>

Print a ~/.ssh/config Host block. The host name is cf-opencode-<workspace>. See Shell and SSH.

ssh-proxy

cf-opencode ssh-proxy <workspace>

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

Browser

browse

cf-opencode browse <workspace>

Open a Browser Run session for a workspace. Print its websocket address. See Browsing.

preview

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.

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.

Type to search…

↑↓ navigate↵ selectEsc close