contenox CLI Reference

contenox is the local AI agent CLI. It runs the Contenox chain engine entirely on your machine.

Global Flags

Persistent flags on the root command (also shown under Global Flags on subcommands). Run contenox --help for the full list.

Flag	Description
`--model <name>`	Default model name (default in tree: `qwen2.5:7b`; override KV via `contenox config set default-model`)
`--provider <type>`	Provider override: `ollama`, `openai`, `vllm`, `gemini`, `vertex-google`, `vertex-anthropic`, `vertex-meta`, `vertex-mistralai`
`--db <path>`	SQLite DB path (default: `~/.contenox/local.db`). The one global database is shared by every workspace.
`--data-dir <path>`	Override the `.contenox` data directory (skips walk-up search). Used to locate the workspace's `workspace.id` and chain files; does not change the database location.
`--timeout`	Max execution time per invocation (default `5m`)
`--context`	Context length hint for the tokenizer
`--ollama`	Ollama base URL (default `http://127.0.0.1:11434`)
`--no-delete-models`	Do not delete undeclared Ollama models (default true for CLI)
`--chain <path>`	Chain JSON for injected `run` / chat when applicable
`--input <value>`	Input string or `@file` (chat / bare run paths)
`--trace`	Structured operation telemetry on stderr
`--steps`	Print execution steps after the result
`--think`	Print model reasoning trace to stderr (thinking models)
`--raw`	Print full structured output (e.g. entire chat JSON)
`--shell`	Enable `local_shell` tools (trusted environments only)
`--local-exec-allowed-dir <dir>`	Restrict `local_shell` to a directory

Subcommands

`contenox` (bare — stateless `run`)

If the first token is not a reserved subcommand (chat, init, run, …), the CLI prepends run. That is stateless: no chat session.

The default chain file is <resolved .contenox>/default-run-chain.json, where .contenox is found by walking up from the current working directory (same rules as contenox init). It is not read from ~/.contenox/ — global state lives in ~/.contenox/local.db, but chain JSON files are project-local. If no --chain is set and the default file is missing, contenox run errors with a hint to run contenox init or pass --chain.

contenox "what can you do?"
echo "summarise README.md" | contenox
contenox --shell "list files here"
contenox --local-exec-allowed-dir . "summarise the README"

Flag	Description
`--shell`	Enable `local_shell` tools (opt-in; command policy is defined in the chain)
`--local-exec-allowed-dir <dir>`	Restrict `local_fs` tools to this directory
`--hitl`	Enable human-in-the-loop approval. Tool calls matching the active policy pause for `y/n` approval in the terminal. Active policy is configured in the workspace Admin → HITL Policies.

`contenox chat`

Sends a message to the active chat session and prints the response. History is persisted across invocations in SQLite.

contenox chat "what can you do?"
echo "summarise README.md" | contenox chat
contenox chat --shell "list files here"

Flag	Description
`--trim N`	Only send last N messages from session history to the model (0 = all)
`--last N`	Print last N user/assistant turns after the reply (0 = only new reply)
`--shell`	Enable `local_shell` tools
`--local-exec-allowed-dir <dir>`	Restrict `local_fs` tools to this directory
`--hitl`	Enable HITL approval prompts (active policy set in workspace HITL Policies)

Manage named chat sessions. Each session maintains its own conversation history.

contenox session list                    # list all sessions (* = active)
contenox session new [name]             # create a session (becomes active)
contenox session switch <name>          # switch to a different session
contenox session show                   # show active session's history
contenox session show <name>            # show any session by name
contenox session show --tail 10         # show last 10 messages
contenox session show --head 5          # show first 5 messages
contenox session show default --tail 6  # tail a non-active session
contenox session delete <name>          # delete session and all messages

`contenox run`

Executes a chain non-interactively. No session history.

contenox run --chain .contenox/chain-nws.json --input-type chat "how is the weather?"
contenox run --chain .contenox/my-chain.json --shell "refactor main.go"

--chain <path>: Optional if <resolved .contenox>/default-run-chain.json exists; otherwise required.
--input-type <type>: string (default), chat, json, int, float, bool — see contenox run --help.
--shell: Enable shell execution for this invocation (use only in trusted environments).
--think / --trace / --steps: Global flags (see table above).

`contenox doctor`

Prints local LLM setup readiness: default model, default provider, and backend reachability.

contenox doctor
contenox doctor --json          # machine-readable output
contenox doctor --skip-cycle    # faster; skips backend sync (status may be stale)

Flag	Description
`--json`	Print results as JSON instead of human-readable text
`--skip-cycle`	Skip syncing backends before the check (faster but may show stale status)

`contenox model`

Manage models in the local Model Registry — a name-to-URL index of GGUF files that can be downloaded for local inference. See Local Models (GGUF) for a full walkthrough.

`contenox model registry-list`

List all curated and user-added registry entries. Does not require a running backend.

contenox model registry-list

`contenox model pull`

Download a curated or custom GGUF model to ~/.contenox/models/<name>/model.gguf.

contenox model pull qwen3-4b                                         # curated model
contenox model pull my-model --url https://huggingface.co/org/repo/resolve/main/model.gguf

After downloading, register the local backend once:

contenox backend add local --type local --url ~/.contenox/models/

Flag	Description
`--url`	Direct GGUF download URL (requires a name as arg[0])

`contenox model add`

contenox model add my-model --url https://huggingface.co/org/repo/resolve/main/model.gguf
contenox model add my-model --url https://... --size 4500000000

Flag	Description
`--url`	Source URL (required)
`--size`	File size in bytes (optional, informational)

`contenox model show`

Display registry details for a model.

contenox model show qwen3-4b

`contenox model rm`

Remove a user-added registry entry by name. Curated entries cannot be removed.

contenox model rm my-model

`contenox model list`

List models currently available from all configured backends (live query, requires at least one backend).

contenox model list

`contenox model set-context`

Override the context window size for a specific model name. Useful when a backend reports a different (or no) context size than the model actually supports.

contenox model set-context qwen2.5:7b           --context 32k
contenox model set-context gpt-5-mini           --context 128k
contenox model set-context gemini-3.1-pro-preview --context 1m

Flag	Description
`--context`	Context window size: bare integer or shorthand (`12k`, `128k`, `1m`). Required.

`contenox tools`

Manage remote OpenAPI tools. See Remote Tools and Tools Allowlist Patterns.

contenox tools add <name> --url <url>
contenox tools add <name> --url <url> --header "Authorization: Bearer $TOKEN" --inject "tenant_id=acme"
contenox tools add <name> --url <url> --spec ~/my-spec.yaml   # local file spec
contenox tools list
contenox tools show <name>
contenox tools update <name> --header <...> --inject <...> --spec <url-or-path>
contenox tools remove <name>

Flag	Description
`--url`	Base URL of the service — where API calls are sent (required)
`--spec`	URL or local file path of the OpenAPI v3 spec (`https://...`, `~/path`, `./path`, `/abs/path`). Local paths stored as `file://` URIs; must exist at registration time. Defaults to `<url>/openapi.json`.
`--header`	HTTP header to inject on every call, e.g. `"Authorization: Bearer $TOKEN"` (repeatable)
`--inject`	Tool call argument to inject and hide from the model, e.g. `"tenant_id=acme"` (repeatable)
`--timeout`	Request timeout in milliseconds (default: 10000)

`contenox init`

Initializes a new .contenox/ directory with default chain files and HITL policy presets. Pass a provider name to pre-configure the default model and provider.

contenox init                    # defaults to ollama
contenox init gemini             # pre-configure for Gemini
contenox init openai             # pre-configure for OpenAI
contenox init --force            # overwrite existing files

Flag	Description
`-f, --force`	Overwrite existing `.contenox/` files

After init, register a backend:

contenox backend add local --type ollama
contenox config set default-model qwen2.5:7b
# Or use Ollama Cloud instead:
contenox backend add ollama-cloud --type ollama --url https://ollama.com/api --api-key-env OLLAMA_API_KEY

`contenox backend`

contenox backend add local        --type ollama
contenox backend add ollama-cloud --type ollama --url https://ollama.com/api --api-key-env OLLAMA_API_KEY
contenox backend add openai       --type openai  --api-key-env OPENAI_API_KEY
contenox backend add gemini       --type gemini  --api-key-env GEMINI_API_KEY
contenox backend add myvllm       --type vllm    --url http://gpu-host:8000
contenox backend add vertex       --type vertex-google \
  --url "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1"

contenox backend list
contenox backend show openai
contenox backend remove myvllm

Flag	Description
`--type`	Backend type: `ollama`, `openai`, `gemini`, `vllm`, `local`, `vertex-google`, `vertex-anthropic`, `vertex-meta`, `vertex-mistralai`
`--url`	Base URL (auto-inferred for openai/gemini; required for vllm and all vertex-* types)
`--api-key-env`	Environment variable holding the API key (preferred)
`--api-key`	API key literal (avoid — use `--api-key-env`)

`contenox config`

Manage persistent CLI defaults stored in SQLite.

contenox config set default-model    qwen2.5:7b
contenox config set default-provider ollama
contenox config set default-chain    .contenox/default-chain.json
contenox config set hitl-policy-name hitl-policy-strict.json

contenox config get default-model
contenox config list

Valid keys: default-model, default-provider, default-chain, hitl-policy-name.

`contenox mcp`

# Shorthand: name + URL (transport defaults to http)
contenox mcp add notion https://mcp.notion.com/mcp --auth-type oauth

# Stdio transport (local process)
contenox mcp add myserver --transport stdio --command npx \
  --args "-y,@modelcontextprotocol/server-filesystem,/tmp"

# SSE transport (remote) with bearer auth
contenox mcp add remote --transport sse --url https://mcp.example.com/sse \
  --auth-type bearer --auth-env MCP_TOKEN

# Inject hidden params into every tool call (model never sees them)
contenox mcp add myserver --transport http --url http://localhost:8090 \
  --header "X-Tenant: acme" \
  --inject "tenant_id=acme" --inject "env=production"

# OAuth with pre-issued client credentials (HubSpot, Salesforce, MS Graph,
# any vendor MCP without RFC 7591 dynamic registration)
contenox mcp add hubspot --transport http --url https://mcp.hubspot.com/ \
  --auth-type oauth \
  --oauth-client-id <client_id from vendor UI> \
  --oauth-client-secret-env HUBSPOT_MCP_CLIENT_SECRET

contenox mcp list
contenox mcp show myserver
contenox mcp update myserver --inject "tenant_id=newvalue"
contenox mcp remove myserver

Flag	Description
`[url]`	URL as a second positional arg — sets `--url` and defaults `--transport` to `http`
`--transport`	Server transport: `stdio`, `sse`, `http`
`--command`	Command to execute (stdio only)
`--args`	Comma-separated command arguments
`--url`	Remote endpoint URL (sse, http)
`--auth-type`	Authentication type: `bearer` or `oauth`
`--auth-env`	Environment variable holding auth token (preferred over `--auth-token`)
`--auth-token`	Auth token literal (avoid — use `--auth-env`)
`--oauth-client-id`	Pre-issued OAuth `client_id` for vendors without RFC 7591 dynamic registration (HubSpot, etc.)
`--oauth-client-secret-env`	Env var holding the pre-issued OAuth `client_secret` (only the var name is stored locally)
`--header`	Additional HTTP header for SSE/HTTP connections, e.g. `"X-Tenant: acme"` (repeatable)
`--inject`	Tool call argument to inject and hide from the model, e.g. `"tenant_id=acme"` (repeatable)

Note

mcp update --header and mcp update --inject each replace the entire corresponding map. Pass all required values in a single update call.

`contenox version`

Prints the current binary version and exits.

contenox version

Environment variables

Variable	Description
`CONTENOX_HITL_ENABLED=true`	Equivalent to passing `--hitl` on every invocation. Useful for making HITL permanent in a shell session or CI environment.

contenox CLI Reference

Global Flags

Subcommands

contenox (bare — stateless run)

contenox chat

contenox run

contenox doctor

contenox model

contenox model registry-list

contenox model pull

contenox model add

contenox model show

contenox model rm

contenox model list

contenox model set-context

contenox tools

contenox init

contenox backend

contenox config

contenox mcp

contenox version