contenox-runtime command reference: every command and flag

contenox-runtime is the Contenox command line: the same agents, providers and permission rules as the desktop app, from a terminal, a script or a CI job. It is installed with the app and uses the same providers, settings and sessions by default (see Install the CLI). This page lists every command, what it is for, and the flags that matter.

Checked against contenox-runtime v1.0.0-rc.5. For the full flag list of any command, add --help:

contenox-runtime mission fire --help

Most used

Set up a provider and model with the interactive wizard:

contenox-runtime setup

Ask something in the active chat session. With no subcommand, the text goes to chat:

contenox-runtime "what does this repository do?"

Run a one-off task without session history, for example from a pipe:

git diff | contenox-runtime run "suggest a commit message"

Start a fresh session, continue it, and read it back:

contenox-runtime session new release-notes
contenox-runtime "draft release notes from the last ten commits"
contenox-runtime session show --tail 4

Run unattended in a script or CI job, with shell access, a time limit and the step list printed at the end:

contenox-runtime run --shell --auto --timeout 10m --steps "run the tests and summarise any failures"

Fire a mission at an agent and wait for the outcome; the exit code tells the script how it went:

contenox-runtime mission fire -q --wait --intent "summarise today's commits"

Check that the default model, providers and connectivity are in order:

contenox-runtime doctor

The —auto trap: --auto turns off approval prompts completely. Every tool call the active policy allows runs without asking. Use it only in a trusted directory or a throwaway CI runner.

Global flags

These work on every command. Put them before or after the subcommand.

Flag	What it does
`--model <name>`	Model for this invocation. Overrides `default-model`. There is no built-in default, so set one with `setup` or `config set`.
`--provider <type>`	Provider type for this invocation, for example `ollama`, `openai`, `gemini`. Overrides `default-provider`.
`--think <level>`	Reasoning level for models that support it: `auto`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Default: `default-think` from config, then `high`.
`--shell`	Give the agent the `local_shell` tool. Use only in trusted environments.
`--local-exec-allowed-dir <dir>`	Limit local tools to this directory.
`--timeout <duration>`	Maximum execution time, for example `30s`, `5m`, `1h`. Default `5m`.
`--trace`	Stream each step to stderr while it runs.
`--steps`	Print the executed steps after the result.
`--raw`	Print the full output, for example the whole chat JSON.
`--max-tokens <n>`	Cap the response length. Overrides `default-max-tokens`.
`--context <n>`	Context length for this invocation.
`--input <value>`	Input text, or `@path` to read it from a file. Default: positional arguments, or stdin when piped.
`-e`, `--editor`	Open `$EDITOR` (or `$VISUAL`) to write the prompt. Piped stdin is preloaded as reference.
`--chain <path>`	Run a specific task chain JSON file instead of the agent’s own.
`--data-dir <path>`	Use a different `.contenox` project directory instead of searching upward from the current directory.
`--db <path>`	Use a different SQLite database instead of the shared one.
`--ollama <url>`	Ollama base URL. Default `http://127.0.0.1:11434`.
`-v`, `--version`	Print the version.

--db points the CLI at a separate database, so providers, sessions and MCP servers registered there do not show up in the desktop app, and the other way round. Leave it out unless you want that separation, for example in CI.

Getting set up

setup

Interactive wizard: pick a provider, enter credentials, choose a default model.

contenox-runtime setup

doctor

Shows whether a default model and provider are set, lists every registered backend, and reports reachability and setup problems for each. Run it when chat or run cannot find a model. With local Ollama and no backend ready, it probes your Ollama URL (OLLAMA_HOST or http://127.0.0.1:11434) and suggests the commands to pull a model and register it.

Flag	What it does
`--json`	Print the results as JSON.
`--skip-cycle`	Skip syncing backends. Faster, but the status may be out of date.

contenox-runtime doctor --json

backend

Subcommand	What it does
`backend add <name>`	Register a provider.
`backend list`	Table of name, type and URL.
`backend show <name>`	Full record as JSON.
`backend login <name>`	Sign in to a ChatGPT subscription backend with a device code.
`backend logout <name>`	Clear a subscription backend’s stored login.
`backend remove <name>`	Delete the registration and its cached model list. Aliases: `rm`, `delete`.

Flags for backend add:

Flag	What it does
`--type <type>`	Provider type (default `ollama`, see the table below).
`--api-key-env <VAR>`	Name of the environment variable that holds the key.
`--api-key <key>`	The key itself. Prefer `--api-key-env`: a literal key ends up in your shell history.
`--url <url>`	Base URL. Inferred for openai, openrouter, anthropic, mistral and gemini.

Supported types:

`--type`	Provider	Needs
`ollama`	Local Ollama, or Ollama Cloud	Nothing locally; for Ollama Cloud `--url https://ollama.com/api --api-key-env OLLAMA_API_KEY`
`openai`	OpenAI API	`--api-key-env`
`openai-codex`	ChatGPT subscription	No key; run `backend login <name>` after adding
`openrouter`	OpenRouter	`--api-key-env OPENROUTER_API_KEY`
`deepseek`	DeepSeek API	`--api-key-env DEEPSEEK_API_KEY`
`anthropic`	Anthropic API	`--api-key-env`
`mistral`	Mistral API	`--api-key-env`
`gemini`	Google Gemini API	`--api-key-env`
`vllm`	Any self-hosted OpenAI-compatible server	`--url`
`bedrock`	AWS Bedrock	`--url` with the region; AWS credentials from the environment
`vertex-google`	Google Cloud Vertex AI	`gcloud auth application-default login` and `GOOGLE_CLOUD_PROJECT`

contenox-runtime backend add openai --type openai --api-key-env OPENAI_API_KEY
contenox-runtime backend add chatgpt --type openai-codex
contenox-runtime backend login chatgpt
contenox-runtime backend add myvllm --type vllm --url http://gpu-host:8000

For a ChatGPT subscription, turn on device-code login in ChatGPT under Settings → Security first; managed workspaces may need an administrator to allow it. Signing in does not change your default model. Per-provider setup is in the provider guides.

model

Inspect models from the registered backends. Alias: models.

Subcommand	What it does
`model list`	Query every backend live and list the models usable now, with their capabilities (chat, embed, prompt, think, vision, context length). Alias: `ls`.
`model set-context <model> --context <size>`	Override the stored context window. Accepts `32k`, `128k`, `1m` or a plain number.
`model capability set <provider> <model>`	Record a capability the provider’s catalog gets wrong: `--think true\|false`, `--vision true\|false`.
`model capability show <provider> <model>`	Show the override for that pair.
`model capability unset <provider> <model>`	Remove the override and go back to what the provider advertises.

contenox-runtime model list
contenox-runtime model set-context qwen3:8b --context 32k
contenox-runtime model capability set ollama my-vlm --vision true

--vision matters for routing: requests with images only go to models marked vision-capable. model capability set --think records whether a model accepts reasoning controls; it is not the same as the global --think level.

config

Persistent defaults, stored in the database.

Subcommand	What it does
`config list`	Every known key, its value and its scope.
`config get <key>`	One value.
`config set <key> <value>`	Set a value.

Keys:

Key	Scope	Meaning
`default-model`	global	Default model name.
`default-provider`	global	Default provider type.
`default-alt-model`, `default-alt-provider`	global	Second model and provider, for chains that use one.
`default-max-tokens`	global	Response token cap.
`default-think`	global	Default reasoning level (`auto`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`).
`default-mission-agent`	global	Agent that `mission fire` uses without `--agent`.
`default-mission-policy`	global	Permission policy that `mission fire` uses without `--policy`.
`telemetry-enabled`	global	Local telemetry logs, `true` or `false`.
`update-check`	global	Automatic update checks, `true` or `false`.
`default-chain`	project	Default chain file for this project.
`hitl-policy-name`	project	Active permission policy file for this project, for example `hitl-policy-strict.json`.

Project keys apply to the current project directory and fall back to the global value when not set there.

contenox-runtime config set default-provider ollama
contenox-runtime config set default-model qwen3:8b
contenox-runtime config set hitl-policy-name hitl-policy-strict.json

init

Create a .contenox/ directory in the current project: an agents.toml, the agent declarations under agents/, and their compiled form under .generated/. You need it when you want project-specific agents or policies; providers and models work without it.

Flag	What it does
`--project`	Create a new project marker here, with a fresh workspace id, instead of reusing a `.contenox` from a parent directory.
`--name <name>`	Display name for the project (default: the directory name).
`--update`	Refresh default files you have not changed to the latest version.
`-f`, `--force`	Overwrite existing files, including ones you edited.

contenox-runtime init --project --name billing-service

Working

chat

The default command. Sends a message to the active session and prints the reply. The first run creates a session called default. Input comes from positional arguments, --input, or stdin.

Flag	What it does
`--auto`	No approval prompts; tool calls go straight through the active policy.
`--trim <n>`	Send only the last N messages of the session history to the model (0 = all).
`--last <n>`	After the reply, print the last N user/assistant turns.

contenox-runtime chat --local-exec-allowed-dir . "summarise the README"
contenox-runtime chat --shell "suggest a commit message from git diff"
echo "summarise README.md" | contenox-runtime

Approvals are on by default: the agent stops and asks in the terminal before writing files or running shell commands, as set by the active permission policy.

run

Run one task without session history: nothing is loaded and nothing is saved. Without --chain, it uses the run agent.

Flag	What it does
`--input <value>`	Input text, or `@path` to read a file.
`--input-type <type>`	How the input is passed: `string` (default), `chat` (one user message), `json`, `int`.
`--chain <path>`	Chain file to run.
`--auto`	No approval prompts.

Input is taken in this order: --input, then positional arguments, then stdin.

git diff | contenox-runtime run "suggest a commit message"
contenox-runtime run --input @main.go "review this file for error handling"
contenox-runtime run --input-type json --chain .contenox/parse-chain.json '{"key":"value"}'

session

Named chat sessions, each with its own history.

Subcommand	What it does
`session new [name]`	Create a session and make it active. Without a name, it is identified by a short id prefix.
`session list`	Sessions in the current scope with message counts; `*` marks the active one.
`session switch <name>`	Make another session active.
`session show [name\|id]`	Print a conversation: the active one, by name, or by id.
`session fork [name]`	Copy the active session into a new one and switch to it.
`session delete <name>`	Delete a session and all its messages. Permanent.
`session workspaces`	Every workspace and session namespace in the database, with counts.

Flags:

Command	Flag	What it does
`session list`	`--all`	Every session in the database.
`session list`	`--workspace <id>`, `--namespace <ns>`	Sessions in one workspace or namespace.
`session show`	`--tail <n>`, `--head <n>`	Only the last or first N messages.
`session fork`	`--summary`	Have the model compact older messages into one summary before forking.
`session fork`	`--keep <n>`	With `--summary`, keep the last N messages word for word (default 8).

contenox-runtime session list --all
contenox-runtime session fork next --summary --keep 12
contenox-runtime session show 6644fc61-fbc6-4e55-9006-b46178625de3

When a long session no longer fits the model’s context window, session fork --summary is the clean way out. The original session stays untouched; you continue in the compacted copy.

Deleting the active session leaves no session active. Create or switch to one before chatting again.

mission

Missions are the headless way to work with an agent. Instead of chatting turn by turn, you fire a one-line intent at an agent under a permission policy (the envelope) and detach. The agent works on its own inside the policy; only a step outside it lands in your approvals queue.

These commands talk to a running contenox-runtime serve over HTTP, by default http://127.0.0.1:32123.

Subcommand	What it does
`mission fire`	Start an agent on an intent under a policy.
`mission list`	Missions, newest first: id, status, agent, policy, last change, intent.
`mission show <mission-id>`	One mission with its status and the reports the agent filed, newest first.
`mission plan <mission-id>`	The mission’s plan: every entry with status and priority, and the revision history.

Flags for mission fire:

Flag	What it does
`--intent <text>`	What the agent is sent to do. Required.
`--agent <name>`	Agent to run. Default: `default-mission-agent`.
`--policy <file>`	Permission policy that bounds it. Default: `default-mission-policy`.
`--cwd <dir>`	Absolute working directory; must be inside an allowed workspace root.
`-q`, `--quiet`	Print only the mission id, for capture in scripts.
`--json`	Print the ids as JSON.
`--wait`	Block until the mission ends; the exit code reports the outcome.
`--wait-timeout <duration>`	Give up after this long (default `5m`).
`--wait-interval <duration>`	Polling interval (default `2s`).

A mission needs both an agent and a policy. Without either, from flags or config, it is refused.

Exit codes with --wait:

Code	Meaning
`0`	Landed, or the agent filed a result.
`1`	Derailed, stuck or abandoned, or the agent stopped without a result.
`2`	The agent filed a blocker and needs you.
`3`	`--wait-timeout` ran out while the agent was still working. Not a success.
`130`	Interrupted with Ctrl-C.

contenox-runtime config set default-mission-agent reviewer
contenox-runtime config set default-mission-policy hitl-policy-strict.json
contenox-runtime mission fire -q --wait --intent "step one" && contenox-runtime mission fire -q --wait --intent "step two"
contenox-runtime mission show 3f9c6e2a

A mission that only files progress or finding reports never produces a result, so --wait keeps waiting and ends with exit code 3 at the timeout. Treat 3 as “unknown”, not as done.

mission, approvals and fleet share two flags: --server <url> and --token <token>, also settable as CONTENOX_SERVER_URL and CONTENOX_SERVER_TOKEN.

approvals

The queue of pending asks from agents running without anyone attached: missions and other headless work held by a running serve.

Subcommand	What it does
`approvals list`	Pending asks, newest first: id, tool, arguments, policy and the rule that matched, which agent and mission it came from, and when it expires. `--json`, `--limit <n>` (default 100).
`approvals answer <id>`	Answer one ask.

There are two kinds of ask:

Kind	Answer with
Permission: a tool call waiting for a verdict	`--approve` or `--deny`
Question: an agent on a mission asks you something	`--reply "<text>"`; the agent gets the text and continues

contenox-runtime approvals list
contenox-runtime approvals answer 3f9c6e2a-1b4d --approve
contenox-runtime approvals answer 7a01c2d4-9e3f --reply "the billing service, not the API gateway"

An unknown, already answered or expired id fails with a non-zero exit code; answering twice is never silently ignored. --approve on a question leaves the agent without an answer, so it records your question as a blocker instead.

fleet

The running agent processes a serve hosts. fleet acts on the processes; the work they were given lives under mission.

Subcommand	What it does
`fleet list`	Every declared agent, idle ones included, with its running instances, their state, open sessions, and the intent each one was sent with. `--json` for the raw records.
`fleet show <instance-id>`	One instance: agent, state, start time, open sessions. `--json`.
`fleet cancel <instance-id>`	Cancel the turn in progress without stopping the instance. Without `--session`, cancels every session on it.
`fleet stop <instance-id>`	Stop the instance and remove it from the board. Stopping an unknown or stopped instance succeeds.

contenox-runtime fleet list
contenox-runtime fleet cancel 9b2e41f0 --session 6644fc61-fbc6-4e55-9006-b46178625de3

state

Step-by-step records of past runs, kept across restarts.

Subcommand	What it does
`state list`	Request ids that have recorded steps.
`state show <reqID>`	Each step’s task, handler, retry, duration, transition and status. `--raw` for JSON.

contenox-runtime state list
contenox-runtime state show <reqID> --raw

Tools and safety

mcp

Subcommand	What it does
`mcp add <name> [url]`	Register a server. With a URL as second argument, the transport defaults to `http`.
`mcp auth <name>`	Run the OAuth sign-in in your browser and store the token.
`mcp list`	Table of name, transport and command or URL.
`mcp show <name>`	Full record as JSON; secrets are masked.
`mcp update <name>`	Change timeout, auth, headers or injected parameters.
`mcp remove <name>`	Delete the registration and its stored credentials. Alias: `rm`.

Flags for mcp add:

Flag	What it does
`--transport <type>`	`stdio` (local process), `sse` or `http` (remote).
`--command <cmd>`, `--args <a,b,c>`	For `stdio`: the command and its comma-separated arguments.
`--url <url>`	For `sse` and `http`.
`--auth-type <type>`	`bearer` or `oauth`.
`--auth-env <VAR>`	Environment variable holding the bearer token. Prefer it over `--auth-token`.
`--oauth-client-id`, `--oauth-client-secret-env`	For OAuth servers without dynamic client registration.
`--header "Key: value"`	Extra HTTP header, repeatable.
`--inject key=value`	Parameter added to every tool call and hidden from the model, repeatable.
`--timeout <seconds>`	Connection timeout in seconds (0 = none).

contenox-runtime mcp add notion https://mcp.notion.com/mcp
contenox-runtime mcp auth notion
contenox-runtime mcp add fs --transport stdio --command npx --args "-y,@modelcontextprotocol/server-filesystem,/tmp"
contenox-runtime mcp add remote --transport sse --url https://mcp.example.com/sse --auth-type bearer --auth-env MCP_TOKEN

On mcp update and tools update, --header and --inject replace the whole existing set, so a header you leave out is dropped. Pass every header you want to keep, not just the new one.

tools

Register an HTTP service with an OpenAPI v3 spec; each of its operations becomes a tool. By default the spec is read from <url>/openapi.json.

Subcommand	What it does
`tools add <name> --url <url>`	Register a service.
`tools list`	Table of name, URL and timeout.
`tools show <name>`	Stored settings (header names, not values) and the tools the service exposes right now.
`tools update <name>`	Change URL, headers, injected parameters, timeout or spec.
`tools remove <name>`	Delete the registration.

Important flags for tools add:

Flag	What it does
`--url <url>`	Base URL. Required.
`--spec <url-or-path>`	Spec at another URL or in a local file.
`--header "Key: value"`	Header on every call, repeatable.
`--inject key=value`	Hidden parameter on every call, repeatable.
`--timeout <ms>`	Request timeout in milliseconds (default 10000).
`--auth-login-url`, `--auth-login-body`	Log in automatically on 401/403. `${ENV_VAR}` placeholders in the body are expanded at run time.
`--auth-extract-cookie`, `--auth-extract-jsonpath`	Where to take the token from in the login response.
`--auth-inject-header`, `--auth-inject-format`	Where to put it on API calls, for example `Authorization` with `Bearer %s`.
`--insecure-skip-tls-verify`	Skip TLS verification for this service only.

contenox-runtime tools add nws --url https://api.weather.gov --timeout 15000
contenox-runtime tools add myapi --url https://api.example.com --header "Authorization: Bearer $TOKEN"

tools --timeout is in milliseconds, mcp --timeout is in seconds, so --timeout 30 on a tool service gives it 30 ms.

Login (--auth-*) and TLS settings can only be set with tools add. To change them, remove the service and add it again.

workspace

The directories a session or mission may use as its working directory. Granting a directory grants everything under it.

Subcommand	What it does
`workspace add <path>`	Grant a directory and register it as a project. `--name` sets a display name.
`workspace list`	The granted directories.
`workspace remove <path>`	Revoke a grant. The directory does not need to exist anymore.
`workspace access <path>...`	Preview what the active permission policy would decide for reading and writing each path, without touching anything.

workspace access asks a running serve and takes --root, --policy, --server and --token.

contenox-runtime workspace add ~/src/billing-service --name billing
contenox-runtime workspace access --policy hitl-policy-strict.json src/main.go .ssh/id_rsa

Grants apply immediately, also to a serve that is already running.

agent

Inspect the agents Contenox discovers from agent files on disk.

Subcommand	What it does
`agent list`	Table of id, name, source, kind and enabled state.
`agent show <name>`	Where the agent comes from and its full configuration.
`agent enable <name>`	Enable an agent.
`agent disable <name>`	Disable an agent.
`agent remove <name>`	Remove the registration. Alias: `rm`.

contenox-runtime agent list
contenox-runtime agent disable reviewer

agent remove does not delete the agent file. If the file still exists, the agent is discovered again on the next start; use agent disable to keep it off.

sandbox

Inspect what shells started by Contenox inherit from the environment.

Subcommand	What it does
`sandbox env`	Print the names (never the values) of the environment variables a spawned shell would inherit under the current scrub policy. `--terminal` shows the interactive-terminal policy instead of the agent-shell one.

The scrub is configured with environment variables: SANDBOX_SHELL_SCRUB (agent shells, default deny-secrets), SANDBOX_TERMINAL_SCRUB (interactive terminal, default off), and the lists SANDBOX_ENV_ALLOW and SANDBOX_ENV_DENY.

contenox-runtime sandbox env
contenox-runtime sandbox env --terminal

The output contains only names, so it is safe to paste into an issue.

shell-env

Environment variables Contenox adds to every shell it starts: the agent’s shell tool and the interactive terminal. They are added on top of what the scrub lets through, so they always win. Changes apply to the next shell.

Subcommand	What it does
`shell-env set KEY=VALUE ...`	Add or override variables.
`shell-env list`	Show them.
`shell-env unset KEY ...`	Remove them.

contenox-runtime shell-env set HTTP_PROXY=http://proxy:3128 GOCACHE=/var/cache/go
contenox-runtime shell-env unset HTTP_PROXY

Values are stored as plain configuration. Do not put secrets here.

Integrations

serve

Start the HTTP API on 127.0.0.1:32123. The desktop app runs it for you; start it yourself on a server or in CI. mission, approvals, fleet and workspace access talk to it. It also serves OpenAI-compatible endpoints (POST /v1/chat/completions, GET /v1/models) and Ollama-compatible ones (GET /api/tags, POST /api/chat, POST /api/generate), so other tools can use your configured default model through it.

Flag	What it does
`--remote`	Listen on all interfaces so other machines on the network can reach it. Requires a token; one is generated if none is set.
`--workspace-root <dir>`	Extra directory a client may choose as a workspace, repeatable. Also `WORKSPACE_ROOTS`, or as positional arguments.
`--oracle <chain>`, `--oracle-policy <policy>`, `--oracle-approves-tool-calls`	Let a chain answer agents’ questions (and, with the last flag, gated tool calls) instead of you. `--oracle off` disables it for this run.

Environment variables: ADDR and PORT to bind a specific address, TOKEN to require a bearer token, TERMINAL_ENABLED=false to turn off the terminal routes, TERMINAL_MAX_SESSIONS (default 8).

contenox-runtime serve
TOKEN=change-me contenox-runtime serve --remote

serve speaks plain HTTP, so with --remote on an untrusted network the traffic is readable. Put a TLS-terminating reverse proxy in front of it.

Housekeeping

cache

Contenox caches each backend’s model list for up to an hour.

Subcommand	What it does
`cache clear`	Drop all cached model lists so the next `chat` or `run` fetches them again.

model list always asks the providers live, but chat and run use the cache. If model list shows a model and chat says no model matched, run contenox-runtime cache clear.

completion

Generate a shell completion script: completion bash, completion zsh, completion fish, completion powershell.

contenox-runtime completion powershell | Out-String | Invoke-Expression

source <(contenox-runtime completion bash)

update

Download and install the latest release from GitHub. Does nothing if you are already on the latest version. When contenox-runtime came with the desktop app, it refuses and tells you to update the app instead, so the app and its command line stay on the same version.

Subcommand	What it does
`update check`	Report whether a newer version exists, without installing.

Turn off update notifications with contenox-runtime config set update-check false.

version

Print the version. Same as contenox-runtime --version.

contenox-runtime version

Install the CLI: get contenox-runtime on your PATH and check it works.
What is MCP?: what an MCP server gives an agent, and what it costs in context.
Use local models with Ollama: the most common backend add setup.
Sign in with a ChatGPT subscription: openai-codex and backend login.