CLI reference

cowork (no command)

cowork

No args: install if needed, start, open the browser at the workbench URL, then block in the foreground until you close the terminal or hit Ctrl-C. Closing the terminal stops the engine.

cowork setup

cowork setup [--yes] [--force]

macOS/Windows: turn this downloaded exe into a real install — copy to <root>/bin, add to your user PATH, install the engine, enable autostart, leave the engine running detached, open the workbench. One action.

cowork install

cowork install [--force]

Install Cowork from the release endpoint (https://cowork-landing-s9uesd.pages.dev/api/release/latest). Default for npm + Bun-compiled CLI.

cowork start

cowork start --headless

The routine runner without the IDE: the daemon in the foreground (systemd, Docker, a terminal) — routines, schedules, webhooks, app auto-updates. Nothing of the IDE is downloaded. A later cowork start on the same box adds the IDE.

cowork start [folder] [--port n] [--force]
[--verbose|-v]

Launch Cowork. If OUR cowork is already running, reports it and exits (single instance, identity-verified). If the default port is taken by a FOREIGN program, moves to a free port and saves it to config (sticky); an explicit --port fails instead. --force replaces a running instance. --verbose passes -vvv to code-server; logs land at <root>/data/logs/<TIMESTAMP>/.

cowork login

Sign this machine in from a terminal (works on a server: paste the address the browser ends on). The session renews itself until cowork logout.

cowork login --email <address>

An account with a password, no browser: the password from a hidden prompt or stdin.

cowork restart

cowork restart

Stop the running Cowork engine and relaunch it.

cowork open

cowork open [--browser]

Open the Cowork workbench. Reuses the running engine; opens the installed Cowork Studio desktop app if present (--browser skips it), else the installed PWA, else a browser tab.

cowork desktop

cowork desktop install|uninstall|status
[--from <zip>|--version <V>|--latest]

The Cowork Studio desktop app (Electron shell): By default this CLI's own release (it matches the engine). Install extracts to /Applications (or the per-user equivalent) and the app self-registers its login item + shortcuts (--register). No cert needed on this path (CLI downloads carry no quarantine).

cowork stop

cowork stop

Stop the running Cowork engine + bridge daemon.

cowork onboarding

cowork onboarding [status|reset [step…]]

The first-run steps, in the terminal: answer what is pending (the same steps the app asks — sign-in itself happens in the app). status lists them; reset asks again (all steps, or the named ones).

cowork logout

cowork logout [--forget]

Sign this machine out of Cowork (every open window follows). --forget also removes that account's local data: its workspaces list, onboarding progress, team-server state, organization access, secrets, the personal server's target here, and the desktop app's browser data. Workspace files are never touched. Never kills a pid it can't verify as cowork's. No-op if nothing is running.

cowork update

cowork update [...flags]

Alias for install. With --force it stops the running engine first and restarts it after the update (open tabs overlay + reload themselves).

cowork self-update

cowork self-update [--version X.Y.Z] [--port n]

One-click update path (spawned by the in-IDE "Update & Restart" button): stop, install through the signed chokepoint, restart, health-verify; rolls back to the previous install on failure.

cowork status

cowork status [--json]

Print versions, state, and the signed-in account.

cowork doctor

cowork doctor [--fix] [--repatch]
[--disable-autostart]

Diagnose the install (patch state, pidfiles, daemon health/drift, watcher binary, logs). --fix applies the repairs it reports. --repatch force re-applies the workbench patches (dev loop — for iterating on theme/CSS assets). --disable-autostart removes the start-at-login setup (re-enable by re-running "cowork install").

cowork --install-extension|--uninstall-extension|--list-extensions

cowork --install-extension <id|vsix>
cowork --uninstall-extension <id>
cowork --list-extensions [--show-versions]

Extension management, passed straight through to the engine (code-server) with cowork's dirs — so whatever the engine's CLI supports works verbatim (or just use the Extensions panel in the workbench).

cowork command

cowork command <id> [--args '<json-array>']
[--timeout <sec>]

Invoke a registered VS Code command inside the RUNNING workbench (via the bridge daemon + the cowork-command-bridge extension). Allowlisted ids only (cowork.*, workbench.profiles.actions.*) — widen via COWORK_COMMAND_ALLOW=<prefix,…>.

cowork consent allow|revoke <value> | list
[--workspace <dir>]

Approve a routine's command ahead of time in a workspace (where no window can ask — headless).

cowork routine

cowork routine run <id> [--args '<json>']
[--workspace <dir>]
[--args -] [--json]

Run a routine — declared in an app's cowork.json — in its own process; result printed, the run audited. --args - reads the JSON from stdin; --json prints the outcome as one JSON line (remote callers).

cowork routine list [--workspace <dir>]
[--json]

The workspace's routines and what each does: active (on its own), on demand, or off.

cowork routine active <id> on|off
[--workspace <dir>] [--json]

The Active switch: on arms the routine's declared schedule, webhook or notifications (and the workspace); off stops it.

cowork routine runs [--workspace <dir> | --all]
[--routine <id>] [--app <name>]
[--agent <id>] [--task <id>]
[--status ok|error|denied]
[--unchanged] [--limit <n>]
[--before <cursor>] [--json]

The routines' runs in this machine's audit log, newest first, a page at a time (--limit, default 50; each page ends with the command for the next). --all = every workspace; --app = one package's runs; --agent / --task = one agent login's runs / one task's; --unchanged adds the runs that changed nothing. On a server: docker exec / ssh.

cowork routine runs --team-server <ts>
[--app <name>] [--device <host>]
[--status ok|error|denied]
[--limit <n>] [--before <cursor>]
[--json]

The runs every runner reported to that team server (its owners and admins).

cowork routine runs show <run-id>
[--workspace <dir> | --all] [--json]

One run: its error, result and log tail (the audit log keeps 7 days).

cowork machine

cowork machine add <id> <[user@]host>
[--port <n>] [--identity <key file>]
[--known-hosts <file>]
[--workspace <folder there>]
[--cli <cowork path there>]

A machine running Cowork headless, opened as a remote window: its files, a terminal there, its routines and executions — over ssh only. Adding connects once to check it; --workspace defaults to the home folder there.

cowork machine list

The machines added on this computer.

cowork machine remove <id>

Forget a machine and close its connection.

cowork machine open <id> [--browser]

Open its remote window, as cowork open does (--browser skips the desktop app).

cowork table

cowork table create <name> | list
[--workspace <dir>]

Create a workspace SQLite table at .cowork/data/<name>.db, listed in Manage Workspace. list shows every .cowork/data/*.db.

cowork queue

cowork queue create <name> [--max-attempts <n>]
[--lease <s>] [--review | --no-review]
[--json]

Create a task queue, or change one's settings: the attempts a task gets (default 3), how long a receiver holds a task (lease, default 300 s), and whether finishing a task needs your review.

cowork queue list [--json]

The workspace's task queues and their counts: needs you, to do, in progress, needs review, done, failed.

cowork queue send <name>
[<text> | --body-file <f> | --stdin]
[--subject <line>]
[--to <agent|owner|anyone>]
[--as <name>] [--review | --no-review]
[--ref <id>] [--meta '<json>']
[--file <path>]… [--delay <s>]
[--json]

Add a task to a workspace task queue — work for agents and scripts (.cowork/local/queues.db, the Tasks view); the first send creates the queue. The subject defaults to the body's first line; --to defaults to anyone, --as (the sender) to owner. --file attaches a copy; --ref is a dedupe key (a second send with it answers the first task); --delay holds the task back <s> seconds.

cowork queue receive <name>
[--as <name> [--mine]] [--lease <s>]
[--wait <s>] [--json]

Take the oldest task to <name> or anyone (--mine: only <name>'s; no --as: unaddressed ones only), with its id and receipt; you hold it for the lease. --wait polls up to <s> seconds (600 at most). Exit 3 = empty.

cowork queue ack <name> <id> --receipt <r>
[--result <text> | --result-file <f>]
[--file <path>]… [--review]
[--to <agent|owner|anyone>] [--json]

Finish a received task: Done, or Needs review with --review (or when the task asks for review); --to hands it on as To do. --result is your entry; --file attaches copies of workspace files to it.

cowork queue nack <name> <id> --receipt <r>
[--delay <s>] [--error <text>]
[--json]

Give it back: To do again after --delay, Failed once the queue's attempts run out; --error is your entry.

cowork queue approve <name> <id> [--json]

Needs review → Done.

cowork queue reject <name> <id> --comment <text>
[--file <path>]… [--json]

Send back a task in Needs review: To do again for the agent who finished it, with --comment as what to change.

cowork queue reply <name> <id>
[<text> | --body-file <f> | --stdin]
[--to <agent|owner|anyone>]
[--as <name>] [--file <path>]…
[--json]

An entry on the task's thread. To an agent or anyone it sends the task to it (reopening a done or failed one); to owner, to nobody, or while the task is in progress, it is a note.

cowork queue retry <name> <id> [--json]

Failed → To do.

cowork queue peek <name> <id> [--json]

One task and its thread, without taking it.

cowork queue items <name> [--agent <name>]
[--q <words>] [--limit <n>]
[--json]
[--view needs_you|todo|in_progress|needs_review|done|failed|all]

A queue's tasks, one line each: --agent = to, from or held by that name; --q = every word; --limit (default 50, at most 200).

cowork queue receivers [<name>] [--json]

The agents seen taking tasks (of one queue, or every queue), and whether each is listening now.

cowork queue summary [--json]

What needs you across every queue, and the open journal entries.

cowork queue delete <name> [<id>] [--yes]

Delete one task and its files; without an id, the whole task queue (needs --yes).

cowork queue purge <name>
[--status done|failed|all]

Delete the queue's done tasks (default), its failed ones, or all of them.

Every verb takes --workspace <dir> (default: the current folder).

cowork journal

cowork journal add <skill>
[<text> | --text-file <f> | --stdin]
[--kind learning|error|note]
[--source <s>] [--json]

Write an entry for a skill — a learning (default), an error or a note — open until an agent folds it into the skill and resolves it.

cowork journal list [--json]

Every skill with entries: how many are open and applied, and where its SKILL.md is.

cowork journal entries <skill>
[--open | --applied | --all] [--json]

A skill's entries, oldest first — the open ones unless --applied or --all. Exit 3 = none open.

cowork journal resolve <skill> [<id>…]

Mark entries applied: the given ids, or every open entry of the skill.

cowork journal delete <id>

Delete one entry.

Every verb takes --workspace <dir> (default: the current folder).

cowork personal-server

cowork personal-server [status] [--json]

This account's personal server: the web inbox mirrors a folder's inbox task queue both ways (/loop /task-inbox [name] takes its tasks). Status: who serves it, when it was last seen. Every verb needs Cowork running and signed in.

cowork personal-server create [<dir>] [--json]

Create it, served by this computer from <dir> (default: the current folder).

cowork personal-server target <dir> [--json]

Change the folder: this computer serves it from <dir>.

cowork personal-server delete --yes [--json]

Delete it: its tasks and files on the server (this computer's inbox stays).

cowork personal-server pull [--json]

Sync now: apply the web inbox's actions here and push the queue's tasks.

cowork mcp-browser

cowork mcp-browser

Stdio MCP server exposing the desktop shell's embedded browser (snapshot→ref→click/fill/read). Point Claude Code or any MCP client at it; the shell must be running. Long-lived — the client owns the lifetime.

cowork app

cowork app list [--json]

Every app in the workspace (a .cowork/apps/<name>/ folder holding cowork.json): version, where it came from (local | <team-server>@<version>, pinned or auto), on/off, whether a newer version is out.

cowork app install <team-server>/<app>[@X.Y.Z]

Install an app from a team server's store into .cowork/apps/<app>/. @X.Y.Z takes a version the store still keeps and PINS it (auto-update leaves it).

cowork app install <https url>
[--title <name>]
[--display tab|sidebar|right]

Install a web site as a site app in .cowork/apps/<name>/: its name, icon and color from the site's web app manifest (the page's title and icon when it has none). It opens in the desktop app, signed in with your browser's accounts — in a tab, or a side bar pane (right: beside Chat).

cowork app update [<app>]
[--replace|--keep-both|--ai-merge
|--skip]

No name: every clean, unpinned update. A name: take the latest (unpins); an app you edited needs one choice (replace / keep both / Claude merges / skip this version).

cowork app remove <app>

Uninstall a store or site install (files you edited are kept). A local app is yours — delete its folder yourself.

cowork app enable|disable <app>

Switch the whole app folder on/off.

cowork app versions <team-server>/<app>

The versions the store keeps (yours marked).

cowork app unpublish <team-server>/<app>[@X.Y.Z]
--yes

Delete it from the store (admin); with @X.Y.Z only that version (not the latest — push a newer one first). Installed copies keep working.

cowork app open <file.jsx|cowork.json>
[--as <mode>]

Open an app in the running workbench — a site app by its .cowork/apps/<name>/cowork.json.

cowork app serve [folder] [--port n] [--no-open]

Run the project's apps as a local webapp (no IDE) at http://127.0.0.1:51190 (--port); its routines run through this computer's daemon.

cowork app build [folder] [--out <dir>]

Write them as a static website: routines run at their deployed URLs (cowork deploy run).

cowork app deploy [folder] [--project <name>]
[--tables <d1-name>]
(every app verb: [--workspace <dir>])

Build + publish to Cloudflare Pages. --tables <d1> also deploys the site's tables endpoint.

cowork push

cowork push [dir]
[--to <team-server> [--remember]]
[--dry-run] [--json]

Publish each app's cowork.json version to a team server's store: dir is an app folder (it holds cowork.json) or a workspace (every .cowork/apps/<name>/cowork.json in it); default the current folder. Where it goes: --to, else the store the app was installed from, else "publishTo" in .cowork/workspace.json; --remember stores the --to team server as that "publishTo". Unchanged content is "up to date" (nothing uploaded). Changed content at an already-published version bumps the patch and writes it back to cowork.json. A version older than the store's is refused — run cowork app update <app> first. After a push the app follows its store like any install, so a collaborator's push reaches you as an update. --dry-run says what it would do.

cowork org

cowork org [me] [--json]

Your organization, the team servers it lets you install from, and the orgs you manage.

cowork org groups [--org <slug>] [--json]

The groups of an org you manage and their members (emails).

cowork org group create <name>
[--members e1,e2] [--org <slug>]

Create a group. Members are emails of people already in the organization.

cowork org group set <name>
[--add-members e1,e2]
[--remove-members e1,e2]
[--org <slug>]

Change a group's members. Applied to the latest saved state (a concurrent save is re-read and re-applied once).

cowork org group delete <name> --yes
[--org <slug>]

Delete a group for the whole organization — the team servers opened to it close to its members.

--org <slug> picks the organization when you manage several.

cowork agent

cowork agent list [--json]

This account's agent logins: name, id, when each last connected, the revoked ones.

cowork agent create <name>
[--workspace <dir>]
cowork agent token <name> [--workspace <dir>]

A login for an agent (Claude Code, Codex …), or a new token for one (the old one stops working). Prints the token ONCE, and the lines that connect a client to this workspace's capabilities.

cowork agent revoke <name> --yes

Sign an agent out for good: its token stops working everywhere.

cowork agent grants [--agent <name>]
[--workspace <dir>] [--json]

What each agent may run here: every routine of the workspace's capabilities, the default and each agent's answer (* = set here; otherwise reads are on, the rest off).

cowork agent grant <cap>/<routine>|<cap>/*
allow|deny|default [--agent <name>]
[--workspace <dir>]

Allow or deny one routine (<cap>/* = every routine of the capability) for one agent, or by default for all; default drops the setting.

cowork agent door [--listen <host:port>]
[--url <url>]
cowork agent door off

The agents' door on its own listener, for agents on other machines: it serves /api/mcp alone. No flags shows it; --url is the address agents connect to (required for 0.0.0.0) — put HTTPS in front of it; off closes it.

cowork credential

cowork credential list [--json]
[--workspace <dir>]

The connections this workspace's capabilities declare: sign-in or key, connected or not, and the capabilities that use each.

cowork credential connect <name>
[--field <k>[=<v>] …]
[--workspace <dir>]

Connect one: a key from its fields (--field token=…, or --field token alone to read it from stdin, out of shell history); a sign-in prints the address to open in a browser.

cowork credential disconnect <name>

Forget it (revoked at the service when it can be) — for every capability that uses it.

cowork deploy

cowork deploy add <id> [--target <t>] [flags]
[--mode local|deployed] [--webhook]
[--schedule "<cron>"] [--secret N]...
[--notifications <app>[,<app>|*]]
[--var K=V]... [--name x]
[--region r] [--role-arn a]
[--hook-token] [--db <d1-name>]
[--cors-origin o] [--workspace <dir>]

A routine's trigger (and deployment), in .cowork/workspace.json#deployments — the only place a schedule, webhook or notifications trigger lives. --schedule = a 5-field cron, --webhook = an HTTP trigger, --notifications = the notifications these apps raise (names as in cowork app list; * = every app's), each one the run's args. --mode local (default): this computer fires the schedule, in local time, once armed (cowork routine active <id> on); deployed: only the copy deploy run put on the target does, in UTC (a webhook answers and notifications fire locally either way). No --target: auto-picks worker|container from the routine's imports (aws-lambda | gcloud-function: explicit only). --db: a Worker's ctx.db D1 database, created at deploy run when missing. Only NAMES land in git — never secret values.

cowork deploy remove <id>

Unregister a deployment (drops its local hooks).

cowork deploy list | status

List deployments (hook URLs, schedule, deployed URL, triggers armed?); status adds per-target tool/auth doctor output.

cowork deploy build <id>

Build the deploy artifact into .cowork/local/deploy-build/ (prints files + warnings).

cowork deploy dev <id> [--port N]

Run the platform's LOCAL emulator in the foreground (workerd / RIE / functions-framework / docker). Ctrl-C to stop.

cowork deploy run <id>
[--consumer-tokens-file <path>]

Deploy for real via the platform CLI; prints the webhook URL. --consumer-tokens-file bakes accepted bearer-token hashes into the deployment.

cowork deploy hooks

Print every local webhook URL for the workspace.

cowork deploy triggers on|off

Arm / disarm local webhooks, schedules and notification triggers for this workspace — the consent gate (off by default; an imported workspace.json never self-activates).

cowork deploy doctor

Per-target tool + auth preflight.

cowork webapp

cowork webapp deploy <dirOrName>
[--project p] [--branch main|staging]
[--routines id,id] [--workspace <dir>]

Stage a static webapp (injecting cowork-routines.js so it can call your deployed routines) and deploy it to Cloudflare Pages.

cowork webapp dev <dirOrName> [--port N]
[--routines id,id]

Serve the staged webapp locally via wrangler pages dev (routines wired to local webhooks).

cowork secrets

cowork secrets set|get|list|delete <name>

The signed-in account's secret store (encrypted, key in the OS keychain). Values are readable only by routines (ctx.secrets.get) and 'secrets get' — never by webviews or daemon routes.

cowork publish

cowork publish [folder] [--items p1,p2]
[--team-server <slug>]...
[--out <file>] [--type <type>]
[--subtype <s>] [--requires <r>]...
[--version X.Y.Z] [--name <n>]
[--title <t>] [--description <d>]
[--tags a,b] [--screenshot]
[--timeout <s>] [--dry-run]

Package this workspace and publish it to a team server's store. No --team-server: packages only and prints the file path (a temp file unless --out). With --team-server: uploads into that team server's store (you must be signed in as one of its admins); name several and each answers on its own. --items packages just those paths (a folder whole, plus any _shared/ helpers above them); exactly one item makes it a workspace-component. Missing paths are reported, not packaged. --type / --subtype default to assets.json's item block, then to what the selection implies; a template needs a subtype. --requires desktop|web says where the item runs. The server assigns the version unless --version pins one. --title / --description / --tags are the store card; a republish keeps any card field it does not state. --screenshot (a workspace or workspace template) makes the folder's last capture — the one Cowork Studio's Home shows — its first screenshot while it has none; look at it first: it is the window as it was, which can show more than the files you publish. --timeout raises the upload's wait (default 120 s). --dry-run uploads nothing. Apps: cowork push. <type>: workspace|workspace-component|template|course

cowork team-server

cowork team-server list

Your team servers (slug, role, counts). A team server is members + a store of things they can install; it is the one place you share through.

cowork team-server create <name> [--desc <t>]
[--visibility public|private]
[--requires-approval]

Create one. Display names aren't unique — the slug is minted for you. Default visibility is private (invite-only); --requires-approval turns a join into a request one of its admins approves.

cowork team-server info|join|leave <team-server>

Show one / join it (--note <text> rides a join request) / leave it.

cowork team-server members [list] <team-server>

Who is in it.

cowork team-server members add <ts> <email>
[--admin]

Add someone by email (--admin makes them an admin). They get the team server's updates.

cowork team-server members remove <ts> <email>

Remove someone. Their Cowork drops the team server (and its courses) at the next updates poll.

cowork team-server requests <team-server>
cowork team-server members approve|deny <ts> <e>

Who is waiting to join; settle each with approve or deny.

cowork team-server store <team-server>

What it publishes (latest version of each item).

cowork team-server install
<team-server>/<item>[@X.Y.Z]
[--dir <path>]

Install an item: a workspace (or a workspace template, untracked) into --dir (default the current folder), a workspace-component into .cowork/apps/<name>/ of the workspace at --dir. @X.Y.Z takes a retained version and pins it. App / routine / skill templates are scaffolded (cowork template install), and courses are subscribed. Cowork does not review what team servers publish.

cowork team-server delete <team-server> --yes

Delete it for everyone (owner only).

cowork template

cowork template install <team-server>/<name>
--name <component> [--dir <path>]
[--host web|desktop]

Scaffold an app / routine / skill template into the workspace at --dir (default the current folder), as the Create menu does. <component> names its folder and files; nothing is written if any target path exists.

cowork component

cowork component install <git url>[#ref]
[--path sub] [--commit sha]
[--allow-unverified]

Install a component straight from a git repo into .cowork/apps/<name>/. Never attested, so it always shows the unverified screen; the override must pin --commit <sha>.

cowork --import-profile

cowork --import-profile <file.code-profile>

Import a profile into the running workbench and switch to it (native .code-profile format). Idempotent: an existing same-name profile is reused (switched to), never duplicated. --timeout <sec> raises the wait budget (default 300s; the workbench keeps applying even if the CLI stops waiting).

cowork --activate-profile

cowork --activate-profile <name>

Switch the running workbench to the named profile (created empty if it doesn't exist).

cowork --export-profile

cowork --export-profile <name> <file>

Export the named profile ("current" = the active one) to a .code-profile file, no save dialog.

cowork --list-profiles

cowork --list-profiles

List the workbench's profiles (name, id, current).

cowork --delete-profile

cowork --delete-profile <name>

Delete the named profile (and its server-side mirror). The Default profile can't be deleted.

cowork --import-workspace

cowork --import-workspace <file.cowork>

Import a local workspace bundle (zip: profile + files). Copies its files into the open workspace folder per assets.json (always | if-newer | if-missing | never), then imports the bundled profile. --dry-run prints the plan, changes nothing; --timeout <sec> raises the profile-apply budget (default 300s; big templates can need more). A bundle may declare a postinstall app (assets.json "events") that opens after import (--no-events suppresses it). To install what a team server publishes, use cowork team-server install.

cowork --export-workspace

cowork --export-workspace <name> <file>

Bundle the named profile ("current" = active) + the files listed in the workspace's assets.json into a .cowork zip. .gitignore is honored (node_modules & co. stay out). --dry-run lists the would-be bundle without exporting.

cowork --help

cowork --help

Show this message.

cowork --version

cowork --version

Print this CLI's version.

Notes

Default install: downloads the prebuilt Cowork bundle for your OS/arch from the release endpoint and seeds <root>. No patches run locally — the bundle is already cooked.

<root> is ~/.cowork-studio (Windows: %LOCALAPPDATA%\Cowork), or $COWORK_HOME.