Skip to content

cli.md

Latest commit

 

History

History
148 lines (109 loc) · 8.23 KB

cli.md

File metadata and controls

148 lines (109 loc) · 8.23 KB
Raw

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.

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

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

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