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.
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
eval "$(skyworker completion bash)"
eval "$(skyworker completion zsh)"
skyworker completion fish > ~/.config/fish/completions/skyworker.fishmcp, ssh, ssh-config, ssh-proxy, browse, notify-key
No flags of their own.