Company OS command line

This page is the terminal reference for operators of Company OS. It lists the commands that exist in the launcher and the operator CLI, their flags, and a few short recipes. For connecting an AI client (Claude Code, Codex, Cursor, and others) see Connect agents.

Two layers, one command name

Company OS has two command-line layers that share the names company-os and companyos.

Layer	What it is	Where it runs
Launcher	A small shell script that starts, stops, installs, and diagnoses the local stack, and hands everything else to the operator CLI.	On the machine that hosts Company OS.
Operator CLI	A Node program that signs in to a Company OS host and calls its API: tasks, runs, approvals, receipts, memory, usage, MCP.	Anywhere that can reach the host, local or remote.

How the names relate, from the source:

• The operator CLI is the company-os / companyos package binary. Both names point at the same file, dist/company-os-cli.js, so companyos task list and company-os task list are the same program. The help text uses both spellings.
• In a source checkout, ./company-os is the launcher entrypoint. It runs scripts/company-os, which handles the lifecycle verbs itself (up, down, desktop, install, and so on) and runs the operator CLI for the rest. If the CLI is not built yet, the launcher builds it first.
• Installed, the command is company-os. This page writes company-os in synopses; from a checkout, type ./company-os.

Older checkouts. Routing the operator commands (task, approvals, receipt, events, ps, and the rest) through ./company-os is recent. If ./company-os task list is not recognised, your launcher only forwards login, logout, connect, and mcp. Run the operator CLI directly with node services/company-os-mcp-server/dist/company-os-cli.js task list, after npm --prefix services/company-os-mcp-server run build.

A few words mean different things in each layer. Check which one you are in:

Word	Launcher (./company-os)	Operator CLI (companyos)
status	Prints the workspace URL when the stack is healthy.	Shows whether this CLI is signed in.
doctor	Static host check; requires --execution-path codex.	Client preflight plus the server's own checks.
chat	Opens the host-governed OMP terminal UI.	Plain terminal chat client (--thread-id).
run	run RUN_ID prints a read-only JSON dump; run pause and run resume go to the operator CLI.	Only run pause and run resume.

From a checkout, the launcher definitions win for status, doctor, chat, and run RUN_ID. To see CLI sign-in state from a checkout, use ./company-os mcp status. The operator CLI's doctor is reachable through the installed companyos binary.

Signing in

Operator commands need a signed-in session.

company-os login                                   # local host, opens a browser
company-os login --console-url https://HOST --device   # remote or headless
company-os logout

• login uses an authorization-code request with PKCE in your browser. The browser is only the authorization handshake.
• login --device prints a Console URL and a one-time code to stderr. Open the URL on a device where you are signed in and enter the code. Use it on a headless terminal.
• The default Console URL is COMPANY_OS_CONSOLE_URL, or http://127.0.0.1:3050 when that is unset. A remote URL must be HTTPS and an origin only (no path or credentials); plain HTTP is accepted only for loopback.
• If you are already signed in, login refuses and tells you to run logout or login --force.
• Only a refresh credential is stored, never a long-lived access key. On macOS it is a mode-0600 file, ~/Library/Application Support/Company OS/cli-refresh.json. On Linux it uses secret-tool; on Windows it uses the Credential Manager vault. logout revokes the CLI session on the host, then deletes the local credential.
• Credentials supplied in the process environment take precedence over the saved session. A saved session takes precedence over an old local host binding.

Output and safety flags

These apply to the operator CLI.

Flag	Meaning
(default)	The canonical Company OS response as pretty-printed JSON. Errors go to stderr as JSON with an error field (approval_required, company_os_api_error, or company_os_cli_error) and the exit code is 1.
--table	Render list payloads as an aligned table. Falls back to JSON when the payload is not a list.
--quiet	Print primary ids only, one per line. Cannot be combined with --table.
--company-id ID	Act on a specific company instead of the one bound to your session. Most commands accept it.
--dry-run	Mutating commands only. Runs the real handler, including reads, then prints the planned request instead of sending it. No --confirm is needed.
--confirm	Required on mutating commands in the default strict mode. See below.
--idempotency-key KEY	Sent as the Idempotency-Key header so a retry of the same request is safe.

--json is not a general flag, and the operator CLI rejects it as an unknown option on most commands. JSON is already the default. --json exists on the mcp subcommands (except serve), on doctor --execution-path codex, and on run RUN_ID (the launcher dump), where it is a no-op because JSON is the only format.

What --confirm means

--confirm acknowledges that you asked for a mutation. It is not a human approval and does not grant authority. The host still applies its own principal, idempotency, spend, settlement, and Gate checks, and can refuse. Without --confirm, a mutating command in strict mode (the default) fails with approval_required. Use --dry-run to see what would be sent.

A recorded approval is a separate object. See Approvals.

Idempotency keys

• task run requires --idempotency-key. The host binds an exact retry to one normalized execution intent and refuses conflicting reuse with HTTP 409.
• task create, run pause, run resume, and mcp connectors enable|disable accept it optionally.
• Pick a key that names the intent, for example task:TASK_ID:run:1.

Start and status

These are launcher verbs.

Command	Purpose
company-os or company-os up	Start or reuse the local workspace and open it. Prints one workspace URL.
company-os up --no-open	Start or reuse without opening a browser.
company-os up --force-restart	Stop checkout-owned listeners first, then start.
company-os up --smoke	Start or reuse, then run the live chat smoke check.
company-os status	Print the workspace URL if API, runtime, and Workspace are healthy.
company-os down (alias stop)	Stop local services started from this checkout.
company-os desktop	Start or reuse Company OS through the Zeron desktop app.
company-os chat [--company ID] [--model MODEL] [--prompt TEXT | --start TEXT]	Open the host-governed terminal UI. --prompt runs one turn and exits; --start opens the UI with TEXT as the first message. --prompt and --start cannot be combined.
company-os tui [--model MODEL] [--company ID]	Open the Zeron terminal projection.
company-os run RUN_ID [--company ID] [--database-url URL]	Print everything recorded about one run as JSON. Read-only; RUN_ID must be a UUID.

The launcher refuses to stop processes it does not own that happen to use the same ports. Ports are set with HSM_COMPANY_CONSOLE_PORT and HSM_CONSOLE_PORT. Defaults and the first-run path are in COMPANY_OS_AGENT_CHAT_LAUNCH.md.

Install lifecycle

Launcher verbs that run the installer (install.sh):

company-os install   [options]
company-os upgrade   [options]    # same as install --upgrade
company-os rollback  [options]    # restore the previous stack and desktop
company-os uninstall [options]    # stop the stack, keep data volumes
company-os purge     [options]    # remove stack, data volumes, desktop app, config

Installer options: --dir PATH (default ~/.hsm-ii), --image REF, --profile companion|full|dev, --no-start, --no-open, --desktop MODE, --desktop-manifest URL, --credential-gateway, --provider-key-file PATH, --telemetry on|off. purge deletes data; uninstall does not.

Other launcher verbs

Command	Purpose
company-os pack validate|preview|test|export PATH [options]	Offline pack tooling. Example: pack preview packs/example --task prepare_report.
company-os registry [args]	Command-registry policy and validation (runs the company-os-command-registry binary through cargo).
company-os doctor --execution-path codex [--json] [--offline]	Static host check for the native Codex execution path. Needs no running stack.
company-os external-runner claim|progress|complete|reconcile --company-id UUID [--run-id UUID --runner-id ID] [options]	Drive an external runner lane. Needs HSM_COMPANY_PRINCIPAL_TOKEN and a bearer token or a 0600 bearer file.

Companies and profiles

Command	Purpose
company-os company list	List the companies you can reach.
company-os company use ID_OR_SLUG	Bind the CLI session to another company. Runs a new authorization, so it may open the browser.
company-os company profile show [--company-id ID]	Show the active document brand profile.
company-os company profile set --file PROFILE.json [--company-id ID] [--confirm | --dry-run]	Store a governed profile override.
company-os company invoice-format show [--company-id ID]	Show the invoice format section.
company-os company invoice-format set --file FILE.json [--company-id ID] [--confirm | --dry-run]	Store an invoice format. The file may be a full profile or only the format.

The file must be a JSON regular file of at most 128 KiB. A full profile has the schema company_os.document_brand_profile.v1 with brand and invoice_format objects. Preview first:

company-os company profile set --file PROFILE.json --dry-run

Tasks

Command	Purpose
company-os task list [--state S] [--agent REF] [--limit N] [--offset N]	List tasks. --limit is 1 to 200.
company-os task show TASK_ID	Show one task.
company-os task create --title TEXT [--specification TEXT] [--owner REF] [--priority N] [--idempotency-key KEY] --confirm	Create a task. --priority is 0 to 100.
company-os task assign TASK_ID --agent REF --confirm	Assign a task to an agent.
company-os task events TASK_ID [--after-seq N] [--limit N]	Page through a task's events.
company-os task run TASK_ID --idempotency-key KEY [--prompt TEXT] [--skill SLUG] [--risk LEVEL] [--backend NAME] [--worker-lane NAME] [--resume-if-stale] [--watch] --confirm	Start a run for a task. --watch prints the start response, then follows the run until it ends.
company-os task cancel TASK_ID [--reason TEXT] --confirm	Set the task state to cancelled.

company-os task create --title "Investigate deployment" --confirm
company-os task run TASK_ID --prompt "Collect evidence" \
  --idempotency-key "task:TASK_ID:run:1" --confirm --watch

Runs and events

Read commands:

Command	Purpose
company-os ps [--task-id ID] [--status S] [--limit N] [--offset N]	List agent runs.
company-os inspect RUN_ID	The run story: canonical status and recorded steps.
company-os what RUN_ID / company-os why RUN_ID	Aliases of inspect. In the current source all three call the same run-story endpoint and return the same payload.
company-os events RUN_ID [--after-seq N] [--through-seq N] [--limit N] [--follow] [--poll-ms N]	Page through execution events, or stream them.
company-os timeline RUN_ID	The run's workflow frames.
company-os diff RUN_ID FROM_FRAME_ID TO_FRAME_ID	Compare two frames.
company-os preview RUN_ID FRAME_ID --operation rewind|fork|replay	Preview a frame operation before proposing it.

events details:

• Without --follow it returns one JSON page. --limit is 0 to 200.
• With --follow it prints one JSON event per line, advances by the server's last_seq, drains once after the run reaches a terminal status, and ends with one summary line (run_id, status, last_seq).
• --follow cannot be combined with --through-seq or --limit 0.
• --poll-ms is 100 to 60000 (default 1000).

Governed controls (all need --confirm unless noted):

Command	Purpose
company-os run pause RUN_ID [--reason TEXT] [--for 30m|2h|3d] [--idempotency-key KEY] --confirm	Pause a run. --for sets a hold of up to 7 days.
company-os run resume RUN_ID [--reason TEXT] [--idempotency-key KEY] --confirm	Resume a paused run.
company-os steer RUN_ID --text TEXT --confirm	Send guidance to a live run.
company-os rewind RUN_ID FRAME_ID	Rewind a run to a frame. Takes no --confirm or --dry-run; the host decides. Run preview first.
company-os replay RUN_ID FRAME_ID	Replay from a frame. Same rules as rewind.
company-os prepare-fork RUN_ID FRAME_ID --source-checkpoint-id ID --branches JSON --confirm	Prepare a successor fork.
company-os select-winner FORK_ID WINNER_BRANCH_ID --rationale TEXT --confirm	Pick the winning branch of a fork.

--branches is a JSON array of 2 to 16 objects, each with label, workspace_slug, and budget_scope:

company-os prepare-fork RUN_ID FRAME_ID --source-checkpoint-id CKPT \
  --branches '[{"label":"a","workspace_slug":"ws-a","budget_scope":"scope-a"},
               {"label":"b","workspace_slug":"ws-b","budget_scope":"scope-b"}]' \
  --dry-run

Approvals

Command	Purpose
company-os approvals [--status S] [--limit N] [--offset N]	List the approval inbox. Rows from before the current envelope format are labelled legacy_unverifiable.
company-os approval show APPROVAL_ID	Show one approval.
company-os approval decide APPROVAL_ID --decision approved|rejected [--reason TEXT] --confirm	Record a decision.
company-os approval approve APPROVAL_ID [--reason TEXT] --confirm	Shorthand for --decision approved.
company-os approval reject APPROVAL_ID [--reason TEXT] --confirm	Shorthand for --decision rejected.

decide refreshes the host's inbox first and binds your choice to the stored presentation, subject, and request digests. It never accepts an approval shape you supply. The host still checks that your principal may decide it. Review with approval show before you decide.

Receipts and verification

Command	Purpose
company-os receipt list	List receipts.
company-os receipt show RECEIPT_ID	Show one receipt.
company-os receipt verify RECEIPT_ID	Check a receipt against its source.
company-os verify task TASK_ID	Replay a task's lifecycle history and compare it with the live projection.
company-os verify run RUN_ID	The same check for a run.

Receipt ids carry a family prefix: terminal:, run_event:, governance:, or spend:. Use the id exactly as receipt list prints it, for example terminal:<receipt-uuid>.

• Terminal receipts are verified by recomputing the stored canonical hash and checking chain linkage and the company head.
• Families without a digest contract return verification_supported=false. That means "not verifiable", never "verified".
• verify task and verify run return verified, has_drift, and drift_kind. Missing history or a replay failure is not reported as verified.

Memory and context

Command	Purpose
company-os memory search [QUERY] [--scope SCOPE] [--latest-only] [--artifact-type TYPE]	Search company memory.
company-os context --run-id RUN_ID	Show the host's context utility output for a run. --run-id is required.

Usage and cost

Command	Purpose
company-os usage [--limit N]	Usage report from the host.
company-os cost [--limit N]	Cost report from the host.
company-os stats [--limit N]	Operator statistics from the host.

All three accept --company-id ID; --limit is 1 to 200. Add --table for a readable view.

Diagnostics

Command	Purpose
companyos doctor [--company-id ID] [--limit N]	Client preflight (credentials, active company binding, server health) plus the host's authoritative checks. Prints a JSON report and exits nonzero if any check fails.
company-os operator-status [--company-id ID] [--limit N]	The host's operator status utility.
company-os utilities	List the operator utilities the host offers.
company-os vocabulary	List the host's operator command vocabulary.
company-os completions zsh	Print a zsh completion script. Only zsh is supported.

The script registers itself for both company-os and companyos. Source it, or save it as _company-os in a directory on your fpath.

The prototype scripts/company-os-today.mjs (a "what needs me" list) is surfaced in Tern. It is read-only and is not a stable launcher verb.

MCP

The mcp command checks the MCP side of a signed-in session and manages host connectors. For client setup see Connect agents.

Command	Purpose
company-os mcp [status]	Verify the company, host, CLI grant, MCP tools, and connectors.
company-os mcp doctor [--client omp]	Show each read-only connection check. Exits nonzero on a failed check.
company-os mcp tools [--search QUERY]	List the tools this session actually exposes.
company-os mcp connect CLIENT	Configure a client. Same as company-os connect CLIENT.
company-os mcp connectors list|show ID|resources ID|prompts ID	Read host-owned connector state.
company-os mcp connectors enable|disable ID --confirm [--idempotency-key KEY]	Request a governed connector change; prints the host's receipt or refusal.
company-os mcp serve --stdio	Serve this session's read-only tools over MCP stdio. Stdout carries protocol data only.

Flags: --company-id UUID on every subcommand except serve and connect; --json on the rest; --table and --quiet on tools and connectors list (--quiet prints tool names or connector keys). CLIENT is omp, codex, claude, cursor, windsurf, gemini, or generic. mcp connect also takes --agent-dir PATH (omp), --project-dir PATH, --api-base URL, --install-dir PATH, --no-start, and --open.

company-os help mcp [topic] and company-os mcp --help print per-command help.

Common workflows

Check readiness

./company-os up --no-open        # start or reuse the stack
./company-os status              # prints the workspace URL when healthy
company-os login                 # once per machine, or when the session lapses
company-os mcp status            # host, grant, tools, connectors
companyos doctor                 # client and server checks; nonzero exit on failure

See what needs approval and decide one

company-os approvals --status pending --table
company-os approval show APPROVAL_ID
company-os approval decide APPROVAL_ID --decision approved \
  --reason "Checked the draft" --dry-run     # preview the request
company-os approval decide APPROVAL_ID --decision approved \
  --reason "Checked the draft" --confirm     # record the decision

Read approval show before deciding. --confirm does not replace your own review and does not widen what your principal may approve.

Follow a run

company-os ps --status running --table
company-os events RUN_ID --follow           # JSONL until the run ends
company-os inspect RUN_ID                   # canonical status and story
company-os run pause RUN_ID --for 2h --reason "Waiting on data" --confirm

To start and watch in one step, use task run ... --watch.

Verify a receipt

company-os receipt list --table
company-os receipt show terminal:RECEIPT_UUID
company-os receipt verify terminal:RECEIPT_UUID
company-os verify run RUN_ID                # replay history against the live run

A receipt whose family has no digest contract reports verification_supported=false. Treat that as unverifiable, not as a pass.

Exit codes and errors

Situation	Result
Operator CLI success	Exit 0.
Operator CLI error (bad flag, API error, refused mutation)	Exit 1, JSON error on stderr.
doctor or mcp doctor with a failed check	Nonzero exit.
Unknown launcher command	Exit 2, with the launcher log path on stderr.
Not logged in. Run \companyos login` first.`	Run company-os login.