CLI reference¶

colossus [OPTIONS] <COMMAND>

Global options¶

Global options appear before the command:

colossus -w /absolute/path/to/repository \
  --config .colossus/config.yaml \
  --approval-mode ask workflow list

Relative --config paths resolve against --workspace. Without it, Colossus selects <workspace>/.colossus/config.yaml and then $COLOSSUS_HOME/config.yaml; files replace rather than merge. A selected malformed file fails without fallback. --workspace does not relocate the Colossus home or state partition. Embedded runtime callers retain current-directory behavior unless they opt into the explicit workspace-aware open API. An active worker publishes its canonical workspace and rejects a client selecting a different one. See Colossus home and workspace resolution.

Interactive TUI and the long-running bare worker default to ask. Other commands executed in-process default to deny; when an active worker handles a command, that worker's configured approval mode applies. Approval mode satisfies an existing approval obligation—it never changes an access or policy decision.

risk-auto is eligible only for model and child-agent shell.run, web.search, bodyless network.http GET, and configured top-level mcp.call effects outside workflows. MCP review requires supported metadata from fresh discovery and evaluates the exact endpoint, server, tool, schema hash, and validated arguments; server-provided descriptions and annotations are advisory. A low-risk allow recommendation produces a request-bound proof. Other network methods, unsupported MCP metadata, and every non-low-risk assessment fall back to explicit approval or denial. Each automatic grant emits a human-readable Automatic approval review notice on the attached terminal or TUI without opening an approval prompt. An unavailable evaluator or invalid assessment emits an Automatic approval review failed warning before Colossus falls back to explicit approval. The warning identifies the sanitized failure category without printing raw provider diagnostics or malformed model output.

Command groups¶

Complete route index¶

Every public leaf route in the current binary appears below. Arguments in uppercase are positional:

Important defaults and bounds¶

config init --development --from PATH validates and preserves the explicitly supplied source document, then replaces storage with fresh isolated development state. Only flags explicitly supplied to that invocation override their corresponding access, sandbox, or storage-protection choice. An inherited encrypted choice receives fresh development key identifiers, and environment-backed protection receives a fresh target anchor path, so the development journal cannot alias the source journal's identity. --sandbox-profile selects the complete platform-isolating preset; omitting it retains the source selection, or uses full access when no source is supplied.

Worker public API flags¶

The installed worker can publish colossus.api.v1alpha1 on an ephemeral 127.0.0.1 port:

colossus --config .colossus/config.yaml worker \
  --public-api-dir "$HOME/.colossus-public-api"

The directory must be absolute. The Unix-native implementation creates only the final directory component when needed and requires the canonical directory to be owned by the current user with mode 0700. It publishes fixed owner-only files endpoint.json and certificate.pem; .public-api.lock prevents a second CLI worker from claiming the same discovery directory. These files contain public discovery and certificate material only.

Application enrollment is an explicit offline worker action:

colossus --config .colossus/config.yaml worker \
  --public-api-dir "$HOME/.colossus-public-api" \
  --enroll-application app:example-desktop \
  --scope runs:execute \
  --scope runs:read \
  --scope runs:control \
  --scope prompts:respond \
  --role primary \
  --credential-keyring-service com.example.desktop \
  --credential-keyring-account colossus-public-api

--scope and --role must each appear at least once. Scope values are exact and must be one of runs:execute, runs:read, runs:control, prompts:respond, or approvals:respond. Repeat --tool EXACT_TOOL_NAME to grant tool ceilings; omitting it denies every tool. agent.delegate is rejected until public application authority can be propagated safely to child runs. Enrollment refuses to run while a private worker endpoint or journal writer exists.

The bearer is written directly to the named OS-keyring entry. It is never printed and there is no flag for bearer input. The non-secret enrollment result includes the stable instance ID and certificate SHA-256; provision those values independently into the application and never trust a pin obtained only from the discovery directory. An existing destination is rejected unless --replace-credential is supplied. Before any mutation, replacement authenticates the stored credential under this public API root and requires the same application ID. Malformed, revoked, foreign-root, or other-application entries fail closed. Replacement then issues the new credential as pending, stores it, durably activates it, and durably revokes the prior credential in that order. Pending credentials cannot authenticate. The result includes both non-secret credential IDs. Use explicit revocation for credentials stored under other keyring entries:

colossus --config .colossus/config.yaml worker \
  --public-api-dir "$HOME/.colossus-public-api" \
  --revoke-credential 018f0000-0000-7000-8000-000000000001

Revocation is durable and idempotent. If a newly issued bearer cannot be written or durably activated, the CLI immediately revokes it and restores the prior destination when applicable before returning an error. If prior-credential revocation cannot be confirmed after replacement activation, the CLI preserves the active new credential at the destination rather than risk restoring an already-revoked token. The sanitized error includes both non-secret credential IDs and instructs the administrator to reconcile and explicitly revoke the prior credential, never either bearer. Native public API directory enforcement currently fails closed on non-Unix platforms.

run --role accepts any configured model role, not only primary. --session and --resume conflict. Plan creation and execution also conflict: run --plan creates a draft, while run --execute-plan PLAN_ID consumes an approved plan; add --goal to execute that plan through bounded Goal Mode.

Clap help is the executable authority for every flag and value:

colossus COMMAND --help
colossus COMMAND SUBCOMMAND --help

JSON output contracts¶

With --output json, one JSON value is written to stdout; diagnostics and optional streamed text stay on stderr. The acknowledged danger-full-access posture warning is emitted on stderr even when stdout is redirected or JSON output is selected. It never contaminates the one-value JSON stdout contract. Lists are arrays unless the command returns a named page or status contract. Important roots are:

Optional values are JSON null; enums and tagged states use documented lowercase snake-case strings. config show is the deliberate exception: it emits strict YAML so references can be reviewed intact. audit show returns an array of metadata-only AuditEvidence records, and audit export emits one such record per line. Evidence includes event identity and ordering, classification, actor/context, timestamps, key ID, algorithm, plaintext hash, previous hash, and record hash. It never includes the journal payload, nonce, or ciphertext. Do not parse human or TUI rendering.

Provider and model Doctor commands remain status-only by default. With --include-provider-response, a failed or transport-incompatible check may add provider_response containing the exact credential-free request URL and JSON body plus at most 16 KiB of response body, the response status and content type, encoding information, and a truncation marker. The configured provider credential is replaced with [REDACTED]. This explicit diagnostic output crosses post-effect policy but is not attached to ordinary runs, TUI events, or durable audit payloads.

A Doctor command exits zero when it successfully produces its diagnostic report, even when the report says the checked provider or model is not ready. Automation must inspect the JSON readiness field instead of treating process success as readiness:

colossus --output json provider doctor PROFILE | jq -e '.ready == true'

Configuration, argument, and report-construction failures remain nonzero.

Common routes¶

colossus -w /path/to/repository config init
colossus -w /path/to/repository config effective
colossus -w /path/to/repository run "Summarize this repository"
colossus -w /path/to/repository --approval-mode risk-auto tui
colossus sessions list
colossus workflow list
colossus audit verify

Machine consumers should pass --output json and treat the command's documented JSON shape as the contract. Human output is optimized for reading and may change presentation without changing application semantics.