CTOX CLI Reference
Commands, flags, IDs, and what they are for.
CTOX has a large CLI because the daemon uses the same surface as a human operator. This page documents the current command surface from the implementation and separates everyday usage from internal, diagnostic, and recovery commands.
Read First
The CLI has three audiences
Some commands are for humans, some are for scripts, and many are for CTOX itself. Treating all of them as equal user-facing commands is what makes the raw command list look chaotic.
Human operator surface
Use ctox, ctox tui, ctox chat, Desktop, and high-level status/update commands.
Operational control surface
Use queue, ticket, schedule, channel, verification, and process-mining commands when debugging, scripting, or recovering state.
Daemon tool surface
CTOX calls commands such as queue, ticket, context, process-mining, and verification commands from worker runs.
Power-user internals
LCM, continuity, source-skill, self-work, and low-level process commands are mostly for inspection, tests, migrations, and repair.
There is real naming debt in the current CLI. For example,
ctox chat uses --workspace, while
ctox queue add uses --workspace-root.
The documentation below calls out those differences instead of
pretending the surface is already perfectly normalized.
Terms and IDs
Identifiers used by commands
The fastest way to make sense of the CLI is to understand which object a command operates on.
| Term | Meaning | Where it appears |
|---|---|---|
thread-key |
Durable conversation or work thread. Use it to attach repeated prompts, channel messages, queue items, or strategy decisions to the same thread. | ctox chat --thread-key, queue add, strategy set |
message-key |
Queue item identifier. It is the handle for blocking, releasing, completing, failing, cancelling, spilling, or restoring queued work. | ctox queue show|block|release|complete|spill |
ticket-key |
External or local ticket key, for example OPS-204. Use it before a CTOX execution case exists. |
ticket show, ticket dry-run, ticket history |
case-id |
CTOX ticket execution case. It appears after the ticket workflow creates an execution case from a ticket. | ticket approve, execute, verify, close, writeback-* |
goal-id / step-id |
Plan identifiers. A plan has a goal; the goal contains executable steps. | plan show, emit-next, complete-step, block-step |
task-id |
Schedule identifier. It controls recurring or deferred tasks. | schedule pause, resume, remove, run-now |
conversation-id |
LCM conversation identifier used by context and continuity internals. | lcm-*, continuity-*, context-health |
workspace / workspace-root |
Filesystem working directory for a run. ctox chat calls it --workspace; queue commands call it --workspace-root. |
ctox chat --workspace, queue add --workspace-root |
Syntax conventions
| Form | Meaning |
|---|---|
<value> |
Required positional or flag value. |
[--flag <value>] |
Optional flag and value. |
<a|b|c> |
One of the listed values. |
... |
Repeatable argument. Example: multiple message keys or statuses. |
--metadata-json, --evidence-json |
Raw JSON string. Quote it in the shell. |
Common Flows
Use the CLI by lifecycle, not alphabetically
Give CTOX work
Use this for a normal operator request.
ctox start
ctox chat "Check this CTOX installation, summarize what is configured, and list the next setup steps before taking on real work."
Inspect queue pressure
Use this when work is blocked, duplicated, or stalled.
ctox queue list --status pending --status leased --status blocked --limit 50
ctox queue show --message-key queue-123
ctox queue release --message-key queue-123 --note "access restored"
Run a ticket case
Use this when work should be tracked by ticket state and evidence.
ctox ticket show --ticket-key OPS-204
ctox ticket dry-run --ticket-key OPS-204
ctox ticket approve --case-id case-123 --status approved
ctox ticket execute --case-id case-123 --summary "deployed"
ctox ticket verify --case-id case-123 --status passed
Schedule a follow-up
Use this when work depends on time, maintenance windows, or retries.
ctox schedule add --name "retry OPS-204" --cron "*/15 * * * *" --prompt "resume OPS-204 if approval exists"
ctox schedule run-now --task-id task-123
Inspect context
Use this when the worker seems to have the wrong working state.
ctox chat-prompt-export --conversation-id 1 --output /tmp/prompt.md
ctox context-retrieve --conversation-id 1 --mode current --query OPS-204
Audit process state
Use this before trusting that a long-running case really closed.
ctox state-invariants
ctox process-mining assert-clean --limit 100
ctox process-mining case case-OPS-204 --limit 200Everyday Commands
Commands humans normally touch
| Command | Purpose | Flags |
|---|---|---|
ctox, ctox tui |
Open the terminal UI. | No required flags. |
ctox start, ctox stop, ctox status |
Start, stop, or inspect the background daemon. | status prints JSON. |
ctox chat <instruction> |
Submit work to the running daemon. | --wait, --thread-key, --workspace, --timeout-secs, --atif-out, --to, --cc, --subject. |
ctox runtime switch <model> <quality|performance> |
Switch the active model/runtime profile. | --context 128k|256k, --timeout <secs>. |
ctox doctor, ctox version |
Inspect install health and version state. | No required flags. |
ctox business-os status, install |
Inspect or install the bundled Business OS template into a separate customer-owned repo. | install --target <empty-dir>, optional --init-git. |
ctox update ..., ctox upgrade |
Check, apply, rollback, or configure release channels. | --stable, --dev, --latest, --version, --from-source, --repo. |
Business OS
Installable business workspace
The Business OS commands deliberately create or inspect a separate application repository. Core upgrades should update CTOX runtime and bundled defaults, but they must not overwrite customer-owned Business OS customizations.
ctox business-os status
ctox business-os install --target <empty-dir> [--init-git]
ctox business status
ctox business install --target <empty-dir> [--init-git]Capabilities
Tool stacks exposed through the CLI
These commands are mostly used by CTOX worker runs and power users. They expose browser, web, scraping, document, and verification capabilities without requiring a model run to rediscover local tooling.
| Command | Purpose | Audience |
|---|---|---|
ctox browser <subcmd> |
Interactive browser automation and browser-state inspection. | Worker/tool surface. |
ctox web <subcmd>, ctox scrape <subcmd> |
Web search/read and scraping/extraction helpers. | Worker/tool surface. |
ctox doc <subcmd> |
Document stack helpers for file-oriented work. | Worker/tool surface. |
ctox verification <subcmd> |
Verification records, evidence checks, and proof-oriented state. | Operational control surface. |
ctox boost status|start|stop |
Temporary boost lease for model/runtime behavior. | Power-user/runtime control. |
Queue
Short-term executable work
Queue commands operate on message-key. The queue is
where immediate work waits, gets leased, blocked, released, failed,
cancelled, completed, or spilled into tickets.
| Command | Use | Important flags |
|---|---|---|
queue add |
Create executable work. | --title, --prompt, optional --thread-key, --workspace-root, --skill, --priority, --parent-message-key. |
queue list, queue show |
Inspect pending or specific work. | --status is repeatable; --limit; --message-key. |
queue edit, reprioritize |
Correct or reprioritize work before execution. | --title, --prompt, --priority, --clear-skill, --clear-workspace-root. |
queue block, release |
Record a blocker or make blocked work executable again. | --reason for block; --note, --clear-note, --priority for release. |
queue complete, fail, cancel |
Close queue work with outcome state. | --note or --reason. |
queue spill, spills, restore |
Move overloaded queue work into ticket-style tracking and restore it later. | --ticket-system, --publish, --state. |
queue repair |
Repair stale or inconsistent queue state. | --dry-run, --mechanical. |
Tickets
Ticket, case, writeback, and knowledge workflow
Ticket commands are the biggest group because they model external work, local fallback tickets, execution cases, approval, verification, writeback, learning, and source-specific knowledge.
| Area | Commands | What to know |
|---|---|---|
| Connectors | ticket init, sync --system, test --system, capabilities --system, sources |
--system local is the current explicit local adapter path. |
| Ticket read path | list, show --ticket-key, history --ticket-key, label-set, label-show, audit |
Use ticket-key while referring to the external/local ticket itself. |
| Case lifecycle | dry-run --ticket-key, cases, case-show --case-id, approve --case-id, execute --case-id, verify --case-id, close --case-id |
Use case-id after CTOX creates an execution case from a ticket. |
| Writeback | take, ack, writeback-comment, writeback-transition |
Writes results or transitions back to the ticket/event source. |
| Local tickets | ticket local create, comment, transition, show |
Local fallback ticket system for development, demos, or self-contained operation. |
| Knowledge | knowledge-bootstrap, knowledge-show, knowledge-load, learn-candidate-* |
Captures durable learnings from ticket work. |
| Source skills | source-skill-set, show, query, import-bundle, review-note |
Associates ticket sources with operating-model skills and runbooks. |
| Self-work and access | self-work-*, access-request-put, autonomy-grant-set, bundle-put |
Internal work management and approval/autonomy metadata. |
Plans and Schedules
Longer work and delayed work
| Command | Purpose | Flags |
|---|---|---|
plan ingest, plan draft |
Create a multi-step goal from a title and prompt. | --title, --prompt. |
plan show, emit-next |
Inspect a plan or emit its next executable queue item. | --goal-id. |
complete-step, fail-step, retry-step, block-step, unblock-step |
Move a plan step through its lifecycle. | --step-id, --result, --reason, --defer-minutes. |
schedule add |
Create recurring or deferred work from a cron expression and prompt. | --name, --cron, --prompt. |
schedule pause|resume|remove|run-now |
Operate an existing scheduled task. | --task-id. |
follow-up evaluate |
Turn a result or blocker into follow-up state. | --goal, --result. |
Channels
Messages, meetings, and asynchronous intake
Channel commands are used to sync, acknowledge, search, and respond to external communication. Meeting and Jami commands are native communication adapters.
ctox channel sync --channel <email|jami|teams|meeting> [--db <path>] [adapter flags]
ctox channel take [--db <path>] [--channel <name>] [--limit <n>] [--lease-owner <owner>]
ctox channel ack [--db <path>] [--status <status>] <message-key>...
ctox channel send --channel <tui|email|jami|teams|meeting> --account-key <key> --thread-key <key> --body <text> [--subject <text>] [--to <addr>]...
ctox channel history --thread-key <key> [--db <path>] [--limit <n>]
ctox channel search --query <text> [--db <path>] [--channel <name>] [--sender <addr>] [--limit <n>]
ctox channel context --thread-key <key> [--db <path>] [--query <text>] [--sender <addr>] [--limit <n>]
ctox meeting join <url> [--name <bot-name>]
ctox meeting schedule <url> --time <ISO-8601>
ctox meeting cancel <url>
ctox meeting transcript <session_id>
ctox jami-daemon --foregroundChannel commands belong to the daemon tool surface more than the everyday human surface. The normal user path is to configure the channel in the TUI, let the daemon sync it, and inspect or repair messages only when routing goes wrong.
Context and LCM
Long-context memory and continuity internals
These commands inspect or repair the context-building machinery. Most users should read the output, not manually mutate it.
| Area | Commands | Purpose |
|---|---|---|
| Messages and summaries | lcm-init, lcm-add-message, lcm-compact, lcm-grep, lcm-describe, lcm-expand, lcm-dump |
Raw messages, summary trees, retrieval, dump, and expansion. |
| Continuity docs | continuity-init, show, apply, update, log, rebuild, forgotten, build-prompt |
Focus, Anchors, and Narrative state used to assemble worker prompts. |
| Health and retrieval | context-health, context-stress, context-retrieve, chat-prompt-export |
Inspect token pressure, retrieve context, and export the assembled prompt artifact. |
Process Mining
Runtime process evidence
Process-mining commands operate on the SQLite event log and formal transition proofs. They are how CTOX reconstructs what happened after a long-running mission.
| Area | Commands | Purpose |
|---|---|---|
| Setup and inventory | ensure, schema, inventory |
Create or inspect process-mining tables and triggers. |
| Events and cases | events, projection, cases, case <case-id>, objects |
Read the event log by event, case, or object relation. |
| Models | transitions, dfg, deadlocks |
SQL-based directly-follows frequency analysis and stuck-activity detection over the live event log. |
| Harness mining | harness-mining stuck-cases, variants, sojourn, conformance, alignment, causal, drift, multiperspective |
Tier 1 + Tier 2 forensic + conformance mining of the agent harness against the declarative state machine. |
| State checks | core-liveness, proofs, state-audit, scan-violations, violations, coverage, assert-clean |
Check graph reachability, illegal transitions, and closure evidence. |
Secrets, Governance, Strategy
State that needs explicit intent
| Command | Purpose | Flags |
|---|---|---|
secret put|get|show|delete |
Store and retrieve named secret references. | --scope, --name, --value, --description, --metadata-json. |
secret intake, memory-rewrite |
Move secrets out of memory/context and replace them with references. | --db, --conversation-id, --match-text, --label. |
strategy set|propose|activate |
Manage canonical vision, mission, or strategic directives. | --kind, --title, --body, --body-file, --author, --reason. |
governance <subcmd> |
Governance decisions and audit state. | Subcommand-specific. |
turn status|end |
Inspect or close the CLI turn ledger. | --turn-id, --status done|blocked|escalated|waiting_external|invalid, --reason. |
Source-Derived Inventory
Current command forms
This inventory is generated from current usage strings in
src/main.rs, src/mission,
src/service, and src/secrets.rs. It is
intentionally exhaustive enough to expose rough edges in the current
CLI design.
ctox boost status | ctox boost start [--minutes <n>] [--model <id>] [--reason <text>] | ctox boost stop
ctox browser <subcmd> [args]
ctox business-os status
ctox business-os install --target <empty-dir> [--init-git]
ctox channel ack [--db <path>] [--status <status>] <message-key>...
ctox chat "<instruction>" [--thread-key <key>] [--workspace <path>] [--wait] [--timeout-secs <n>] [--atif-out <path>] [--to <addr> ...] [--cc <addr> ...] [--subject <text>]
ctox doc <subcmd> [args]
ctox context-health <db-path> <conversation-id> [latest-user-prompt] [token-budget]
ctox context-stress <db-path> [conversation-id] [iterations] [token-budget]
ctox continuity-apply <db-path> <conversation-id> <narrative|anchors|focus> <diff-path>
ctox continuity-build-prompt <db-path> <conversation-id> <narrative|anchors|focus>
ctox continuity-forgotten <db-path> <conversation-id> [narrative|anchors|focus] [query]
ctox continuity-init <db-path> <conversation-id>
ctox continuity-log <db-path> <conversation-id> [narrative|anchors|focus]
ctox continuity-rebuild <db-path> <conversation-id> <narrative|anchors|focus>
ctox continuity-show <db-path> <conversation-id> [narrative|anchors|focus]
ctox continuity-update --kind <narrative|anchors|focus> --mode <full|replace|diff> [--conversation-id <id>] [--db <path>] [--find <text>] [--replace <text>]
ctox follow-up evaluate --goal <text> --result <text>
ctox jami-daemon --foreground
ctox lcm-add-message <db-path> <conversation-id> <role> <content>
ctox lcm-compact <db-path> <conversation-id> [token-budget] [--force]
ctox lcm-describe <db-path> <summary-id>
ctox lcm-dump <db-path> <conversation-id>
ctox lcm-expand <db-path> <summary-id> [depth] [--messages] [token-cap]
ctox lcm-grep <db-path> <conversation-id|all> <scope> <mode> <query> [limit]
ctox lcm-init <db-path>
ctox lcm-refresh-continuity <db-path> <conversation-id>
ctox lcm-run-fixture <db-path> <fixture-path>
ctox lcm-show-continuity <db-path> <conversation-id>
ctox meeting <join|schedule|cancel|status|transcript> [args]
ctox meeting cancel <url>
ctox meeting dump-script <url>
ctox meeting join <url> [--name <bot-name>]
ctox meeting schedule <url> --time <ISO-8601>
ctox meeting transcript <session_id>
ctox plan block-step --step-id <id> --reason <text>
ctox plan complete-step --step-id <id> [--result <text>]
ctox plan draft --title <label> --prompt <text>
ctox plan emit-next --goal-id <id>
ctox plan fail-step --step-id <id> --reason <text>
ctox plan ingest --title <label> --prompt <text>
ctox plan retry-step --step-id <id>
ctox plan show --goal-id <id>
ctox plan unblock-step --step-id <id> [--defer-minutes <n>]
ctox queue add --title <label> --prompt <text> [--thread-key <key>] [--workspace-root <path>] [--skill <name>] [--priority <urgent|high|normal|low>] [--parent-message-key <key>]
ctox queue block --message-key <key> --reason <text>
ctox queue cancel --message-key <key> [--reason <text>]
ctox queue complete --message-key <key> [--note <text>]
ctox queue edit --message-key <key> [--title <label>] [--prompt <text>] [--thread-key <key>] [--workspace-root <path>] [--clear-workspace-root] [--skill <name>] [--clear-skill] [--priority <urgent|high|normal|low>]
ctox queue fail --message-key <key> --reason <text>
ctox queue release --message-key <key> [--priority <urgent|high|normal|low>] [--clear-note] [--note <text>]
ctox queue reprioritize --message-key <key> --priority <urgent|high|normal|low>
ctox queue restore --message-key <key> [--priority <urgent|high|normal|low>] [--note <text>]
ctox queue show --message-key <key>
ctox queue spill --message-key <key> [--ticket-system <name>] [--reason <text>] [--skill <name>] [--publish]
ctox runtime embedding-doctor
ctox runtime embedding-smoke [--token-id <id>]
ctox runtime switch <model> <quality|performance> [--context 128k|256k] [--timeout <secs>]
ctox runtime stt-doctor
ctox runtime stt-smoke <wav-path>
ctox runtime stt-realtime-smoke <wav-path>
ctox runtime tts-doctor
ctox runtime tts-smoke [--text <text>]
ctox schedule add --name <label> --cron '<expr>' --prompt <text>
ctox schedule pause --task-id <id>
ctox schedule remove --task-id <id>
ctox schedule resume --task-id <id>
ctox schedule run-now --task-id <id>
ctox scrape <subcmd> [args]
ctox secret delete --scope <scope> --name <name>
ctox secret get --scope <scope> --name <name>
ctox secret intake --scope <scope> --name <name> --value <text> [--description <text>] [--metadata-json <json>] [--db <path> --conversation-id <id> --match-text <text> [--label <text>]]
ctox secret memory-rewrite --db <path> --conversation-id <id> --scope <scope> --name <name> --match-text <text> [--label <text>]
ctox secret put --scope <scope> --name <name> --value <text> [--description <text>] [--metadata-json <json>]
ctox secret show --scope <scope> --name <name>
ctox strategy activate --directive-id <id> [--decided-by <name>] [--reason <text>]
ctox strategy propose --kind <vision|mission|...> --title <text> --body <text>|--body-file <path> [--conversation-id <id>|--thread-key <key>] [--author <name>] [--reason <text>]
ctox strategy set --kind <vision|mission|...> --title <text> --body <text>|--body-file <path> [--conversation-id <id>|--thread-key <key>] [--author <name>] [--reason <text>]
ctox service --foreground [--autonomy progressive|balanced|defensive]
ctox ticket access-request-put --system <name> --title <title> --body <text> [--required-scopes <csv>] [--secret-refs <csv>] [--channels <csv>] [--skill <name>] [--metadata-json <json>] [--publish]
ctox ticket ack --status <handled|failed|duplicate|blocked> <event-key>...
ctox ticket approve --case-id <id> --status <approved|rejected>
ctox ticket audit [--ticket-key <key>] [--limit <n>]
ctox ticket autonomy-grant-list
ctox ticket autonomy-grant-set --label <label> --approval-mode <mode> --autonomy-level <level>
ctox ticket bundle-list
ctox ticket bundle-put --label <label> --runbook-id <id> --policy-id <id>
ctox ticket capabilities --system <name>
ctox ticket cases [--ticket-key <key>] [--limit <n>]
ctox ticket case-show --case-id <id>
ctox ticket close --case-id <id> [--summary <text>]
ctox ticket dry-run --ticket-key <key> [--understanding <text>]
ctox ticket execute --case-id <id> --summary <text>
ctox ticket history --ticket-key <key> [--limit <n>]
ctox ticket history-export --system <name> --output <path>
ctox ticket knowledge-bootstrap --system <name>
ctox ticket knowledge-list [--system <name>] [--domain <name>] [--status <value>] [--limit <n>]
ctox ticket knowledge-load --ticket-key <key> [--domains <csv>]
ctox ticket knowledge-show --system <name> --domain <name> --key <value>
ctox ticket label-set --ticket-key <key> --label <label>
ctox ticket label-show --ticket-key <key>
ctox ticket learn-candidate-create --case-id <id> --summary <text> [--actions <json-array>] [--evidence-json <json>]
ctox ticket learn-candidate-decide --candidate-id <id> --status <approved|rejected>
ctox ticket learn-candidate-list [--label <label>] [--status <value>] [--limit <n>]
ctox ticket list [--system <name>] [--limit <n>]
ctox ticket local comment --ticket-id <id> --body <text>
ctox ticket local create --title <text> --body <text>
ctox ticket local show --ticket-id <id>
ctox ticket local transition --ticket-id <id> --status <value>
ctox ticket monitoring-ingest --system <name> --snapshot-json <json> [--key <value>] [--title <text>] [--summary <text>] [--status <value>]
ctox ticket self-work-assign --work-id <id> --assignee <name> [--assigned-by <actor>] [--rationale <text>]
ctox ticket self-work-note --work-id <id> --body <text> [--authored-by <actor>] [--visibility <internal|public>]
ctox ticket self-work-publish --work-id <id>
ctox ticket self-work-put --system <name> --kind <kind> --title <title> --body <text> [--skill <name>] [--metadata-json <json>] [--publish]
ctox ticket self-work-show --work-id <id>
ctox ticket self-work-transition --work-id <id> --state <value> [--transitioned-by <actor>] [--note <text>] [--visibility <internal|public>]
ctox ticket self-work-list [--system <name>] [--state <value>] [--limit <n>]
ctox ticket show --ticket-key <key>
ctox ticket source-skill-compose-reply (--ticket-key <key> | --case-id <id>) [--send-policy <suggestion|draft|send>] [--subject <text>] [--body-only]
ctox ticket source-skill-import-bundle --system <name> --bundle-dir <path> [--embedding-model <model>] [--skip-embeddings]
ctox ticket source-skill-query --system <name> --query <text> [--top-k <n>]
ctox ticket source-skill-review-note (--ticket-key <key> | --case-id <id>) --body <text> [--top-k <n>]
ctox ticket source-skill-resolve (--ticket-key <key> | --case-id <id>) [--top-k <n>]
ctox ticket source-skill-set --system <name> --skill <name> [--archetype <value>] [--status <active|inactive>] [--origin <value>] [--artifact-path <path>] [--notes <text>]
ctox ticket source-skill-show --system <name>
ctox ticket sync --system <local|zammad>
ctox ticket test --system <local>
ctox ticket verify --case-id <id> --status <passed|failed> [--summary <text>]
ctox ticket writeback-comment --case-id <id> --body <text>
ctox ticket writeback-transition --case-id <id> --state <value> [--body <text>] [--internal]
ctox turn end --status <done|blocked|escalated|waiting_external|invalid> [--reason <text>] [--turn-id <id>]
ctox update check | apply | rollback | status | channel ...
ctox verification <subcmd> [args]
ctox web <subcmd> [args]