Skip to content

CLI reference

Every skyworker command, with its flags.

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

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

No flags of their own.

Type to search…

↑↓ navigate↵ selectEsc close