---
title: "CLI reference"
description: "Every skyworker command, with its flags."
---

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

# CLI reference

Run `skyworker --help` for the list. Run `skyworker <command> --help` for one command.

## Global options

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

A failure is one line on stderr: `Failed: <cause> — fix: <action>`. With `--json` it is `{"ok":false,"error":"..."}` on stdout. An unknown command or flag exits with code 2. Other failures exit with code 1.

## Installer commands

The npm package `skyworker` handles these. Every other command runs in the build that it downloads.

| Command | What it does |
| --- | --- |
| `login` | Store the licence key in `~/.skyworker/license-key`. It reads the key from the terminal with no echo, or from stdin. The key is never an argument. |
| `logout` | Remove the licence key from this machine. The builds and your install stay. |
| `update` | Get the newest build. Then run `skyworker upgrade` to put it on your Cloudflare account. |
| `installer` | Show the key state, the build on this machine and the release server URL. |

## All commands

| Command | Group | Summary |
| --- | --- | --- |
| `init` | Set up | Check this machine and your Cloudflare account, deploy, and save the install. |
| `upgrade` | Set up | Redeploy the Worker and image from this CLI version. Keeps the control token. |
| `uninstall [--yes]` | Set up | List, then with `--yes` delete, the Worker, its container app and images. |
| `doctor` | Set up | Check this machine, the install and the Worker. Never starts a workspace. |
| `pair` | Set up | Let a phone or another browser use the web client. Prints a QR code that works once. |
| `devices` | Set up | List the paired devices, or revoke one. |
| `git-token [--remove]` | Set up | Let workspaces use GitHub. The token stays in the Worker. |
| `notify-url [--remove]` | Set up | Set where the Worker POSTs task results and notes. |
| `notify-key` | Set up | Print the key that signs the POSTs to the notify URL. A secret. |
| `skill [--install]` | Set up | Print the handoff skill for agents, or install it. |
| `completion <bash\|zsh\|fish>` | Set up | Print a tab-completion script. |
| `connect [workspace]` | Workspaces | Wake or create a workspace and open it in local OpenCode. |
| `run "<task>" [workspace]` | Workspaces | Hand a task to an agent in the workspace of this checkout, and return. |
| `tasks [workspace \| session \| workspace:session]` | Workspaces | Tasks handed off with `run`, newest first, or one task. Wakes nothing. |
| `sessions [workspace]` | Workspaces | Sessions of every harness across your workspaces. Wakes nothing. |
| `status [workspace]` | Workspaces | Show one workspace, or the install. |
| `list` | Workspaces | Workspaces this machine connected to, with their state. |
| `logs <workspace>` | Workspaces | The redacted `opencode serve` log. |
| `pause <workspace>` | Workspaces | Snapshot the disk and scale the workspace to zero. |
| `delete <workspace>` | Workspaces | Destroy the workspace. Its snapshot data expires on its own. |
| `rebuild <workspace>` | Workspaces | Move a workspace onto the deployed image, keeping `/home/user`. Stops its agent. |
| `cp <from> <to>` | Workspaces | Copy a file or folder between workspaces, or between a workspace and this machine. |
| `store [rm <name>]` | Workspaces | List the files in the store, or remove one. |
| `skills [push\|remove\|default] [name...]` | Workspaces | Copy skills from this machine into a workspace. |
| `mcp` | Workspaces | Serve `run` and `tasks` to an agent as MCP tools, over stdio. |
| `shell <workspace>` | Terminal | Open a terminal in the workspace, inside tmux. |
| `ssh <workspace> [-- ssh args]` | Terminal | SSH into the workspace as `user`, over the Worker. |
| `ssh-config <workspace>` | Terminal | Print a `~/.ssh/config` `Host` block for the workspace. |
| `ssh-proxy <workspace>` | Terminal | The `ProxyCommand` of `ssh`. You do not run it yourself. |
| `browse <workspace>` | Browser | Open a browser session for a workspace and print its address. |
| `preview [workspace] <port...>` | Browser | Open a dev server of the workspace at `http://localhost:<port>`. |

## Flags per command

### init

| Flag | Meaning |
| --- | --- |
| `--account <id>` | The account, when the login sees more than one. Or `CLOUDFLARE_ACCOUNT_ID`. |
| `--name <name>` | The Worker name. The default is `skyworker`. |
| `--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 (a Custom Domain). The zone must be in the account. `upgrade` keeps it. |
| `--adopt` | Replace a Worker of that name that this machine did not deploy. It also replaces DNS records or another Worker's Custom Domain on `--domain`. A replaced Worker gets a new control token. |
| `--url <url>` | Deploy nothing. Use a Worker that is deployed, from another machine or at a new URL. It needs the control token in `~/.skyworker/control-token` or `SKYWORKER_CONTROL_TOKEN`. |
| `--yes`, `-y` | Never prompt. `--json` and a stdin that is not a terminal imply it. |
| `--no-github` | Do not set up GitHub now. |
| `--no-skill` | Do not install the handoff skill on this machine. |

`--url` and `--domain` do not go together. The name `--url` here is not the global option.

### upgrade

Flags: `--token-file <path>`, `--domain <hostname>` (the default is the recorded one), `--adopt`, `--yes`, `--no-github`, `--no-skill`. The flags mean the same as for `init`. `upgrade` fails with `nothing to upgrade on this machine` when no install is recorded.

### uninstall

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

### doctor

No flags of its own. It checks Node, OpenCode (and warns when it is not version 2), `ssh`, the Worker URL, the control token, the web client, the Worker version, the AI and Browser Run bindings, and the GitHub token on the Worker. It exits with 1 when a check fails.

### pair

| Flag | Meaning |
| --- | --- |
| `--no-terminal` | The device cannot open a terminal in a workspace. |
| `--json` | Print the link in place of the QR code. |

### devices

| Flag | Meaning |
| --- | --- |
| `--revoke <id>` | The device cannot use the web client any more, at once. |

### git-token

| Flag | Meaning |
| --- | --- |
| `--remove` | Delete the token from the Worker. |
| `--token-file <path>` | A file with a Cloudflare API token. |

The command reads the GitHub token from stdin, or asks for it on a terminal with no echo.

### notify-url

| Flag | Meaning |
| --- | --- |
| `--remove` | Delete the URL from the Worker. |
| `--token-file <path>` | A file with a Cloudflare API token. |

The command reads the URL from stdin, or asks for it with no echo. The URL must use https, hold no user or password, and name a public host.

### skill

| Flag | Meaning |
| --- | --- |
| `--install` | Install the skill. Without it, print the skill. |
| `--claude` | With `--install`: copy it to `~/.claude/skills/skyworker-handoff/`. |
| `--opencode` | With `--install`: copy it to `~/.config/opencode/skills/skyworker-handoff/`. |
| `--dir <path>` | With `--install`: copy it to `<path>/skyworker-handoff/`. |
| `--force` | Replace a file there that differs. |

### connect

| Flag | Meaning |
| --- | --- |
| `--dir <path>` | The project directory in the workspace. The default is `/home/user/project`. |
| `--repo <url>` | The git remote to clone when the workspace has no snapshot yet. |
| `--branch <name>` | The branch to check out. |
| `--no-attach` | Do not open OpenCode. Print one JSON line with `workspace`, `url` and `username`. |
| `--skills <a,b\|all>` | Copy these skills into the workspace first. Off by default. |
| `--continue`, `-c` | Open the last session of the workspace. |
| `--session`, `-s <id>` | Open that session. |

### run

| Flag | Meaning |
| --- | --- |
| `--harness <name>` | `opencode` (default), `claude-code` or `codex`. |
| `--model <provider/model>` | The model. With another harness, a model name of that harness. |
| `--title <text>` | The session title. |
| `--branch <name>` | Start from this branch as it is on origin. |
| `--auto` | OpenCode runs with no permission prompts. A deny rule still applies. Claude Code and Codex always run with no prompts. |
| `--new` | Start the task in a new workspace, named `<checkout>-<short id>`. |
| `--worktree` | Start the task in a new git worktree in the workspace. |
| `--no-push` | The agent commits and does not push. |
| `--allow-dirty` | Start anyway, and say what the workspace will not see. |
| `--skills <a,b\|all>` | Copy these skills into the workspace first. |
| `--schema <file.json>` | The last message must end with a json block that matches this JSON Schema. |
| `--wait` | Wait until the task leaves `working`, then print its result. |
| `--follow` | The same, and show the progress of the agent live. |
| `--timeout <minutes>` | How long `--wait` and `--follow` wait. The default is 60. |
| `--continues <n>` | Automatic continues after a pause or a platform stop. The default is 3. Zero is off. The most is 20. |
| `--max-hours <n>` | Stop the task after this many hours of work. The default is 24. The most is 720. |
| `--max-cost <dollars>` | Stop the task when its cost reaches this. The default is off. |

Exit code with `--wait` or `--follow`: 0 done, 1 failed, 2 waiting, 3 timed out, 4 stopped. `--new` and `--worktree` do not go together. `--new` takes no workspace argument.

### tasks

| Flag | Meaning |
| --- | --- |
| `--workspace <id>` | The workspace of the task. |
| `--unseen` | List only the tasks that ended and are not read yet. |
| `--reply "<text>"` | With a session: send one more message to it. |
| `--continue` | With a session: go on with a task that stopped. |
| `--max-hours <n>` | With `--continue` or `--reply`: the new time budget. |
| `--max-cost <dollars>` | With `--continue` or `--reply`: the new cost budget. |
| `--cancel` | With a session: interrupt the turn that runs. Wakes nothing. |
| `--wait` | With a session: wait until the task leaves `working`. |
| `--follow` | With a session: the same, and show progress live. |
| `--timeout <minutes>` | How long `--wait` and `--follow` wait. The default is 60. |
| `--pull` | With a session: fetch the task's branch from origin into this checkout. It goes alone. |

`--cancel` goes alone. `--continue` and `--reply` are two replies: use one. `--json` with a session prints the result record.

### sessions

| Flag | Meaning |
| --- | --- |
| `--live` | Ask the workspaces themselves, not the session index. A running workspace answers live. A paused one answers with the list saved at its last pause. |

### logs

| Flag | Meaning |
| --- | --- |
| `--lines <n>` | How many lines from the end. The default is 100. The most is 1000. |

### pause, delete, rebuild, status, list

No flags of their own. `pause`, `delete` and `rebuild` need a workspace.

### cp

| Flag | Meaning |
| --- | --- |
| `--force` | Replace a target that exists. |

A side is `<workspace>:<path>`, a local path or `store:<name>`. See [Workspaces](https://skyworker.system3inference.dev/docs/guides/workspaces/#copy-files).

### store

| Flag | Meaning |
| --- | --- |
| `--prefix <text>` | List only the names that start with it. |

`store rm <name>` removes a file. The store is off unless the `store` setting is `true`.

### skills

| Form | Meaning |
| --- | --- |
| `skills` | List the skills on this machine, and which are in the workspace. |
| `skills push a b` | Copy skills `a` and `b`. This replaces the copy that is there. |
| `skills push --all` | Copy every skill found here. |
| `skills push` | With no names: copy the saved list. |
| `skills remove a` | Delete skill `a` from the workspace. |
| `skills default a b` | Save a list. Every new workspace gets these on its first connect. |
| `skills default --none` | Clear the list. |

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

### shell

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

### preview

With no flag, `preview` forwards the port over the SSH of the workspace to `http://localhost:<port>` on this machine. Nothing is public. The forward runs until you press Ctrl-C. It needs `ssh` and the local password of the workspace, so run `connect` on this machine first.

| Flag | Meaning |
| --- | --- |
| `--no-open` | Do not open the browser. |
| `--web` | Use a URL on the Worker behind a one-time sign-in link. |
| `--public` | Make a URL that needs no password, until `--stop`. It needs the control token. |
| `--stop` | Remove the public URL of the port, or of every port without one. |
| `--list` | List the public URLs of the workspace. |
| `--json` | Print one JSON document with the Worker URL and its sign-in link, as `--web`. It makes no forward. |

### completion

```sh
eval "$(skyworker completion bash)"
eval "$(skyworker completion zsh)"
skyworker completion fish > ~/.config/fish/completions/skyworker.fish
```

### mcp, ssh, ssh-config, ssh-proxy, browse, notify-key

No flags of their own.

Source: https://skyworker.system3inference.dev/docs/reference/cli/index.mdx
