CoWork OS CLI

CoWork OS is now both a desktop app and a terminal agent surface. The desktop GUI remains the primary operator console for agents, artifacts, approvals, automations, Mission Control, and settings. The cowork command adds a fast local command-line entrypoint for starting work without opening a separate Control Plane session.

What cowork Runs

The CLI has two local modes plus local management commands:

• cowork opens an interactive terminal UI with the CoWork welcome panel, command shortcuts, local workspace/provider status, and a prompt for task input.
• cowork run "<task>" runs a one-shot local task and streams the result back to the terminal.
• Commands such as cowork status, cowork sessions list, cowork tools list, cowork mcp list, cowork backup create, and cowork security audit read or update the same local settings/database used by the desktop app.

By default, these local modes do not require COWORK_CONTROL_PLANE_TOKEN. They use the same local CoWork profile, database, provider settings, workspaces, skills, and MCP connector configuration that the desktop app uses.

Remote Control Plane mode is explicit:

cowork run "summarize the active project" --remote

Use --remote only when you intentionally want the CLI to call a running remote Control Plane endpoint. In that mode, configure COWORK_CONTROL_PLANE_URL and COWORK_CONTROL_PLANE_TOKEN, or pass the equivalent CLI options.

CoWork Pulse controls

These commands operate on the selected local profile. Pulse is off by default; pulse is an alias for telemetry.

cowork telemetry status
cowork telemetry show
cowork telemetry on
cowork telemetry off
cowork telemetry send
cowork telemetry reset --yes
cowork telemetry delete --yes

show prints a queued aggregate or a preview; send still requires full-day consent and does not force an ineligible day to upload. off discards queued packages but does not delete remote data or abort a request already running. reset creates a new identity without removing old remote rows and loses the old deletion token. Use delete before reset if you want the previous identity's data removed. Successful delete removes remote rows and disables Pulse locally; failed deletion retains local state for retry.

See CoWork Pulse for fields, destination, daily timing, and known limitations.

First Run

Install globally from npm:

npm install -g cowork-os
cowork

From a source checkout:

npm run setup
npm run build:cli
cowork

The source launcher can build missing CLI artifacts automatically, but npm run build:cli is the fastest explicit path when iterating locally.

If you have already configured providers in the desktop app, cowork should pick them up. On macOS and Windows, the CLI prefers the bundled Electron runtime in ELECTRON_RUN_AS_NODE=1 mode for local commands. That gives terminal commands normal stdout/stderr while preserving the Electron/Node ABI required by native modules and encrypted desktop settings. If Electron is unavailable, the CLI can fall back to the Node runner, but OS-encrypted desktop credentials and native modules may not be readable from that fallback process.

Commands

cowork
cowork run "who are you?"
cowork run "inspect this repo and list the riskiest files" --workspace /path/to/repo
cowork run "inspect this repo" --access-profile ask_for_approval
cowork run "run the trusted local build" --access-profile full_access
cowork run "return a compact status report" --json
cowork providers list
cowork providers configure openai --model gpt-5.5
cowork providers fallback list
cowork workspace list
cowork sessions list
cowork sessions export <sessionId> --output session.json
cowork logs latest
cowork tools list
cowork mcp list
cowork skills audit
cowork models list
cowork backup create --output cowork-backup.json
cowork backup restore cowork-backup.json --dry-run
cowork security audit
cowork security status --refresh
cowork security findings
cowork security finding <findingId> acknowledged
cowork security decisions
cowork security inventory --refresh
cowork security scan
cowork security check-rules
cowork security hooks status codex
cowork security hooks install codex --yes
cowork security case build incident-123 --task-id <taskId>
cowork security prune --yes
cowork prompt-size "estimate this prompt"
cowork completions zsh
cowork dashboard status
cowork tail <taskId>
cowork approvals
cowork run "run this on the remote node" --remote
cowork --help

Interactive mode accepts free-text tasks and slash commands:

• /doctor checks runtime, database, workspace, provider, and local CLI readiness.
• /providers list shows locally configured model routes.
• /providers configure <provider> saves common provider settings locally through the same encrypted settings store used by the desktop app.
• /workspace list shows known local workspaces.
• /workspace use <path> sets the working workspace for the session.
• /exit leaves the CLI.

Access Profiles

cowork run uses the same access-profile resolver as the desktop app. Select a built-in profile or an administrator/workspace-defined custom id with --access-profile:

cowork run "review the repository" --access-profile ask_for_approval
cowork run "run the local test suite" --access-profile approve_for_me
cowork run "perform this trusted local maintenance" --access-profile full_access
cowork run "inspect the bounded project" --access-profile review-repository

The profile controls sandboxing, approval and reviewer behavior, command-tool availability, filesystem roots/rules, and network/domain policy. --remote sends the requested id to the target Control Plane, where it is resolved and enforced using that node's settings and administrator policy. Credentials and local browser sessions are not transferred by selecting a profile.

Within a named profile's granted boundary, reads, edits, and sandboxed local commands run without approval prompts. An exception requests only the additional authority it needs. A profile with approval: never denies missing authority without waiting; it does not disable the sandbox.

Local CLI tasks share the desktop Jev settings and decision ledger. When Active JEV harness mode reviews a headless task, it cannot open an interactive approval prompt. A task started with an explicit non-interactive profile such as --access-profile full_access proceeds only when the exact operation is already authorized; a concerning Jev observation is recorded in the policy trace and does not create a second approval request. Missing authority, hard policy, security, protected-path, network, and operating-system consent requirements still fail closed. See Jev Decision Support and Harness for the full decision and telemetry contract.

--permission-mode remains available for older integrations and maps to the legacy compatibility path. --shell is also retained as a compatibility alias and maps to the bounded ask_for_approval profile; it is not an unrestricted shell switch. Prefer --access-profile for new scripts.

If a named profile is missing, invalid, or unavailable on the target, the task fails closed with a read-only unavailable profile and may pause for user action. A later approval cannot widen that profile. See Access Profiles for the full field reference and migration contract.

approve and reject use a local desktop handoff by default. The CLI sends the response to the already-running CoWork OS app through the app's single-instance bridge, so the live task runtime can wake and continue without Control Plane. If no desktop app is running, open CoWork OS and retry, or use cowork approve <approvalId> --remote / cowork reject <approvalId> --remote against a running Control Plane target.

Local Management Commands

These command groups are local-first and do not require a Control Plane token:

• cowork version and cowork status show installed runtime, provider, workspace, task, MCP, and tool readiness.
• cowork sessions ... manages local task lineages. Rename/delete/prune use CLI metadata; delete and prune require --yes and archive sessions from CLI lists instead of deleting task history.
• cowork logs latest|tail|grep reads local developer logs when developer logging has captured them.
• cowork tools list|info|enable|disable updates built-in tool category or per-tool settings.
• cowork mcp list|add|remove|enable|disable|test updates local MCP server settings.
• cowork skills list|info|audit inspects locally registered skills.
• cowork models list shows the current provider model list and stored model presets.
• cowork providers fallback list|add|remove manages global provider fallback routes.
• cowork backup create|restore exports local workspaces, recent task metadata, provider settings, tool settings, MCP settings, and skills. Task content, approval payloads, and MCP secrets are redacted unless --include-secrets --yes is passed. Restore previews are safe with --dry-run; actual restore requires --yes, validates settings, restores settings only, and keeps restored MCP servers disabled until re-enabled.
• cowork security audit checks local provider/tool/permission posture. Warnings return a non-zero exit code so CI can fail on risky local settings.
• cowork security rules list|remove inspects or removes workspace permission rules. Removal requires --yes.
• cowork security status|findings|finding|decisions|inventory|scan|check-rules|hooks|case|prune operates the optional Numbat agent-security runtime. Mutating operations require --yes where shown by cowork security --help.
• cowork prompt-size and cowork prompt-preview provide quick prompt diagnostics.
• cowork completions zsh|bash|fish prints shell completion snippets.
• cowork dashboard and cowork open task <taskId> launch the desktop app/deeplink without using the Control Plane.

Runtime Model

The CLI is not a separate product backend. It is another surface over the same local runtime contracts:

• bin/cowork-cli.js resolves the installed package, ensures CLI build output exists, and launches the TypeScript-compiled CLI.
• src/cli/main.ts owns argument parsing, the interactive terminal UI, slash commands, local diagnostics, and remote-mode dispatch.
• src/cli/direct-run.ts owns one-shot local execution and local management commands when the CLI runs with the bundled Electron-as-Node runtime.
• src/electron/main.ts supports --cowork-cli-direct-run, a hidden app-entry mode retained for packaged app-entry compatibility, plus a single-instance approval handoff for local approval responses.

Local one-shot execution initializes the database, settings, provider routing, workspace resolution, skills, MCP servers, and agent daemon, then creates a task and waits for completion. The CLI daemon disables startup recovery for that process so it does not recover, resume, or rewrite GUI-owned tasks while the desktop app is also running.

Interactive cowork and local cowork run can be used while the GUI is installed and already configured. They share local profile state, but each CLI task is still a distinct task run with its own terminal output.

Agent Security Commands

Numbat agent security is disabled by default. Configure it in Settings > System & Security > Agent Security or through the admin policy before expecting scans or enforcement decisions. Local commands use the desktop profile; add --remote only for an intentional Control Plane call, where state-changing operations require admin scope.

status, findings, decisions, and inventory are inspection commands. scan and check-rules run bounded checks. Finding-state changes, hook installation/removal, case-bundle creation, and retention pruning are explicit operator actions. Case verification checks the bundle manifest and checksums without changing runtime policy.

See Agent Security with Numbat for policy defaults, rule provenance, failure behavior, retention, external hook constraints, and troubleshooting.

Security And Credentials

• Local CLI mode keeps provider credentials and task data on the machine, following the desktop app's local-first model.
• Normal local CLI use does not need a Control Plane token.
• --remote is the token-gated path and should be treated like any other remote device operation.
• --json emits structured JSONL events for machine consumers without exposing hidden reasoning.
• Numbat decisions are an additional restriction layer. They cannot grant a permission, suppress an approval, or weaken sandbox and network controls.
• Access profiles are resolved before the CLI task starts. A profile can be constrained by admin policy, hard guardrails, protected paths, and export/location consent; CLI mode does not bypass those boundaries.
• Set COWORK_CLI_DEBUG=1 when you need verbose local runtime diagnostics.

Troubleshooting

If cowork reports missing CLI runtime output, run:

npm run build:cli

If cowork run prints Missing token, check whether --remote was passed or a remote alias is being used. Local one-shot tasks should run without a Control Plane token.

If the CLI cannot see providers already configured in the desktop app, confirm the same install/profile is being used and try:

COWORK_CLI_DEBUG=1 cowork run "who are you?"

If the hidden Electron runner is unavailable in a source checkout, build the app-entry artifacts:

npm run build:electron
npm run build:cli

See Troubleshooting for failure-specific recovery steps.