Command reference

One section per operation a command executes: the synopsis, the specification, the inputs with the flag or positional that carries them, worked examples, what the operation writes where, the statuses it reports and the conditions it refuses on. Every word here comes from the operation’s own servicecontract.Contract, so a change to the contract changes this document and task -d runtime cli:reference rebuilds it.

Services

The declared services whose operations a command reaches.

automatic-local-setup

Review and configure independent AI roles.

Choose local, remote or cloud routes for each role. Review connections, models, devices, settings and required downloads, then verify the selected group before saving it atomically.

inference-configuration

Configure AI roles independently

Configure Chat, Recovery, Autocomplete and Workspace Search independently using cloud accounts, custom endpoints or local models.

model-cache

Refresh cached provider model catalogs.

Provider model catalogs are cached between discovery runs. Clearing them forces the next provider refresh to fetch the current catalog without changing provider or model configuration.

license

Sign this machine in to Contenox and apply the licence it receives.

A Contenox account grants each paired machine a licence: the hosted origin inference is proxied through, the bearer that authenticates it, the models the plan allows and the capabilities they carry. Signing in pairs the machine with the relay, checks in for the licence and applies it: the hosted provider is configured with the licence’s origin and bearer, the chat role takes the licence’s default model and every other role takes the first granted model whose discovered capability serves it, each verified by a real request.

A machine nobody has signed in is a state, not a failure: the status operation reports it as awaiting sign-in and names the control that completes it. A role no granted model can serve is reported with the reason rather than left unassigned in silence.

inference-model-registration

Register a model on this connection

Declare a model identity, context and operation capabilities when this endpoint has no usable model catalog. Registration is scoped to this connection. Each assigned role still requires production verification.

instructed-code-completion

Declare an instructed code-completion operation

Declare whether a provider model uses the chat completion chain or one bounded prompt operation. Assigning the model still requires successful execution of the selected IDE completion operation.

local-model-usage

Inspect locally recorded model usage.

Model calls made by this installation are recorded by model and may be inspected across the installation or within one conversation session.

Operations with a command

contenox-cli auto

Set up local AI

service	automatic-local-setup
operation	apply
synopsis	contenox-cli auto

Acquire the recommended artifacts and verify real chat, completion and retrieval operations before saving all required role assignments.

input	type	required	reached by	values
plan	object	yes	the operation’s request	—

output
stdout	Acquisition progress, then the verified roles that were saved.
stderr	Progress narration for a long download.
format	text

status	when	meaning
0	every required role is acquired and verified	the assignments are saved together

Refuses when:

• an artifact cannot be acquired — names the artifact and the failure; nothing is saved
• a role fails verification — names the role and the operation that failed; the current configuration is preserved

contenox-cli auto

Acquire and verify the selected roles before committing them together.

service	automatic-local-setup
operation	apply-recommended
synopsis	contenox-cli auto

Acquire and verify the selected roles before committing them together, so a partially available group is never saved as a configured one.

input	type	required	reached by	values
plan	object	yes	the operation’s request	—

output
stdout	Progress, then the roles that were verified and saved.
stderr	Progress narration for a long download.
format	text

status	when	meaning
0	every selected role verifies	the assignments are saved together

Refuses when:

• a selected role fails verification — names the role and preserves the current configuration

contenox-cli auto

Select an alternative and recheck the group’s resource and scheduling limits.

service	automatic-local-setup
operation	choose
synopsis	contenox-cli auto

Select an alternative route for one role and recheck the group’s resource and scheduling limits, so a choice that cannot run with the others is refused before it is applied.

input	type	required	reached by	values
plan	object	yes	the operation’s request	—
role	string	yes	the operation’s request	primary, alternative, autocomplete, next-edit, embedding
alternative	number	no	the operation’s request	—

output
stdout	The selected alternative and the rechecked group.
format	text

status	when	meaning
0	the alternative fits the group’s limits	the plan now carries the chosen route

Refuses when:

• the alternative conflicts with another role’s resources — names both roles and the resource they contend for
• the alternative index does not exist — names the range the plan offers

contenox-cli auto

Inspect the recommended local AI setup without changing the machine.

service	automatic-local-setup
operation	plan
synopsis	contenox-cli auto
options	—dry-run inspects without installing

Select a current curated, permissively licensed model that is curated as able to run a multi-step tool loop, holding at least 32768 tokens of usable context in this machine’s memory. Capability gates the choice and context qualifies it: a larger window on a model that cannot use it is not a capability. Selection uses available memory, the model’s native context ceiling, and the KV cache type the worker is configured with (CONTENOX_LLAMA_KV_CACHE_TYPE; q8_0 halves what a window costs in device memory). Cold/planner capacity does not count. Origin restricts the model developer’s region. Downloads use Hugging Face by default (HF_ENDPOINT overrides it; HF_TOKEN optionally authenticates).

The worker and model are installed, a harmless tool call is verified, and only then are native defaults saved. Subsequent runs reuse the configured eligible model; —refresh selects again. Setup uses native inference.

output
stdout	The machine’s summary, the selected model with its download size, and the estimated hot context.
format	text, or the plan as JSON when —dry-run is given

status	when	meaning
0	a plan is produced	nothing was installed and no default changed

Refuses when:

• no curated model fits this machine’s selection budget — names the budget, the KV cache type and the smallest model that would fit

contenox-cli auto

Recommend roles independently across allowed connections.

service	automatic-local-setup
operation	recommend
synopsis	contenox-cli auto

Recommend a route for every role independently, across the connections the constraints allow, without changing any assignment.

input	type	required	reached by	values
recommendation	object	yes	the operation’s request	—

output
stdout	One recommendation per role with the connection it selects.
format	text

status	when	meaning
0	every role has a recommendation	nothing was assigned

Refuses when:

• no allowed connection can serve a role — names the role and the constraint that excluded every connection

contenox-cli backend add

Connect an account or endpoint

service	inference-configuration
operation	connect
synopsis	contenox-cli backend add
flags	--type --url --api-key --api-key-env --credential-source --credential-file

Register a named LLM backend endpoint in the local SQLite database.

The —type flag determines which provider protocol is used. openai, anthropic, gemini Cloud providers. Base URL inferred if —url is omitted. Requires —api-key-env. openai-codex ChatGPT subscription. Fixed endpoint; use backend login, no API key. modeld Native inference worker (local or remote gRPC). ollama Local daemon (requires ‘ollama serve’) or hosted Ollama Cloud (use —url https://ollama.com/api and —api-key-env OLLAMA_API_KEY). vllm Self-hosted OpenAI-compatible endpoint (requires —url). vertex-google Google Cloud Vertex AI / Gemini (requires gcloud auth application-default login). scripted-test TEST ONLY. Replays a scripted dialog from a JSON file (requires —script).

API keys should be passed via —api-key-env (reads from environment) rather than —api-key (inline literal) to avoid leaking secrets into shell history.

The scripted-test type is a fake: it calls no model and replays the turns in its —script file in order, one per model turn. Every surface that names the active provider shows “scripted-test”, and ‘contenox-cli doctor’ warns while it is the default. It proves the machinery (chain loop, tool dispatch, HITL gate), not the agent’s judgement — you wrote the tool calls, so no real model was asked to choose them.

Examples: contenox-cli backend add ollama —type ollama contenox-cli backend add ollama-cloud —type ollama —url https://ollama.com/api —api-key-env OLLAMA_API_KEY contenox-cli backend add openai —type openai —api-key-env OPENAI_API_KEY contenox-cli backend add gemini —type gemini —api-key-env GEMINI_API_KEY contenox-cli backend add myvllm —type vllm —url http://gpu-host:8000 contenox-cli backend add contenox —type contenox contenox-cli backend add scripted —type scripted-test —script ./dialog.json

input	type	required	reached by	values
id	string	no	the operation’s request	—
name	string	yes	positional 1	—
provider	string	yes	--type	—
url	string	yes	--url	—
apiKey	secret	no	--api-key	—
apiKeyEnv	string	no	--api-key-env	—
credentialSource	string	yes	--credential-source	—
credentialFile	string	no	--credential-file	—

Examples:

• contenox-cli backend add ollama --type ollama — A local daemon.
• contenox-cli backend add ollama-cloud --type ollama --url https://ollama.com/api --api-key-env OLLAMA_API_KEY — A hosted Ollama endpoint.
• contenox-cli backend add openai --type openai --api-key-env OPENAI_API_KEY — A cloud provider with an inferred base URL.
• contenox-cli backend add myvllm --type vllm --url http://gpu-host:8000 — A self-hosted OpenAI-compatible endpoint.

output
stdout	The saved connection and the models discovery found for it.
stderr	A discovery failure, which stays attached to the saved connection.
format	text

status	when	meaning
0	the connection is saved	the connection is usable by every role that names it

Refuses when:

• the provider type is not one this runtime speaks — names the unsupported type and lists the supported ones
• a required field for the chosen type is absent — names the field, such as a URL for a self-hosted endpoint
• the endpoint is unreachable — reports the discovery failure and keeps the saved connection

contenox-cli cache

Describe model-catalog cache maintenance.

service	model-cache
operation	describe
synopsis	contenox-cli cache

Provider model catalogs are cached between discovery runs. Clearing them forces the next provider refresh to fetch the current catalog without changing provider or model configuration.

output
stdout	The service description, then the operations this service exposes.
format	text

status	when	meaning
0	the description is rendered	nothing was changed

contenox-cli cache clear

Clear cached provider model catalogs.

service	model-cache
operation	clear
synopsis	contenox-cli cache clear

Clear cached provider model catalogs.

output
stdout	How many cached provider model catalogs were removed.
format	text

status	when	meaning
0	every cached catalog was removed	the next provider refresh fetches a current catalog

Refuses when:

• the local store cannot be opened — names the store that failed; an unreadable cache is never reported as an empty one

contenox-cli config list

Read AI configuration

service	inference-configuration
operation	read
synopsis	contenox-cli config list

List common defaults, their stored values and inherited values before session, agent and model constraints. —all includes advanced settings; —describe adds complete descriptions and the locations of settings held outside this store.

output
stdout	Every declared setting with the value in force, its scope and its fallback.
format	text

status	when	meaning
0	the settings are rendered	an unset setting is reported as inherited rather than as missing

Refuses when:

• the local store cannot be read — names the store that failed; an unreadable store is never rendered as an unset configuration

contenox-cli config set

Verify and apply reviewed roles

service	inference-configuration
operation	apply
synopsis	contenox-cli config set

Set a default for future launches. Names use dotted namespaces and snake_case fields; units are part of numeric names. Legacy names remain aliases of the same row.

Examples: contenox-cli config set inference.context.window_tokens 131072 contenox-cli config set inference.generation.max_output_tokens 8192 contenox-cli config set inference.reasoning.effort high contenox-cli config set inference.autocomplete.model qwen2.5-coder:7b contenox-cli config set execution.permissions.policy hitl-policy-strict.json

Use —scope global to set the fallback for a workspace-scoped key. Other keys are global. Session pickers and slash commands do not save defaults. Use ‘config get —explain’ to inspect inheritance and constraints.

input	type	required	reached by	values
proposals	array	yes	the operation’s request	—

Examples:

• contenox-cli config set inference.context.window_tokens 131072 — Session history window in tokens.
• contenox-cli config set inference.generation.max_output_tokens 8192 — Response token cap.
• contenox-cli config set inference.reasoning.effort high — Reasoning effort for supported models.
• contenox-cli config set inference.autocomplete.model qwen2.5-coder:7b — Autocomplete model.
• contenox-cli config set execution.permissions.policy hitl-policy-strict.json — Envelope a dispatched unit runs under.

output
stdout	The setting and the value now in force.
format	text

status	when	meaning
0	the value is stored	the next launch reads it

Refuses when:

• the key is not a declared setting — names the unknown key and lists the valid ones
• the value is rejected by its own rule — names the constraint, such as a boolean or a non-negative count
• the requested scope does not apply to the key — names the key as global and points at the session control for a temporary override

contenox-cli config set

Verify and apply device and resource settings

service	inference-configuration
operation	configure-resources
synopsis	contenox-cli config set

Write the device, context, thread, batch, KV cache and residency settings of one role. The proposed settings are exercised through the role before they are committed, so a configuration that cannot run is refused rather than saved.

input	type	required	reached by	values
role	string	yes	the operation’s request	primary, alternative, autocomplete, next-edit, embedding
options	object	no	the operation’s request	—

output
stdout	The setting and the value now in force.
format	text

status	when	meaning
0	the settings are exercised and committed	the role runs with the resources that were verified

Refuses when:

• the role cannot run with the proposed resources — names the role and the resource that failed
• the role or an assignment changed during verification — requires another review instead of committing over the change

contenox-cli license refresh

Check in for the current licence and re-apply it when it changed.

service	license
operation	refresh
synopsis	contenox-cli license refresh

Checks in with the relay for the licence the account currently grants this paired machine and, when the origin, bearer or granted models differ from the applied licence, applies the new one the way sign-in does. A machine that is not paired is refused and told to sign in.

Examples:

• contenox-cli license refresh — Pick up a changed plan or a rotated bearer.

output
stdout	The sign-in state after the check-in.
format	text

status	when	meaning
0	the licence is current	the applied configuration matches what the account grants

Refuses when:

• this machine is not paired — names the sign-in operation
• the relay answers no licence for this machine — names the relay’s answer

contenox-cli license sign-in

Pair this machine with a pairing key, check in for its licence and apply it.

service	license
operation	sign-in
synopsis	contenox-cli license sign-in
flags	--key --endpoint --instance-name

Redeems a one-time pairing key minted in the Contenox app for this machine’s relay credentials, checks in for the licence the account grants, and applies it. A machine that is already paired resumes under that pairing — it checks in and applies without redeeming the key — and redeems the key only when the relay no longer honours the pairing it holds. The applied licence means: the hosted provider is configured with the licence’s origin and bearer, the chat role takes the licence’s default model, and autocomplete, next edit and workspace search take the first granted model whose discovered capability serves the role. Every assignment is verified by a real request before it is stored. A role no granted model can serve is reported with the reason.

input	type	required	reached by	values
key	string	yes	--key	—
endpoint	string	no	--endpoint	—
instanceName	string	no	--instance-name	—

Examples:

• contenox-cli license sign-in --key <pairing key> — Pair, check in and apply the licence.

output
stdout	The sign-in state after the licence was applied.
format	text

status	when	meaning
0	the licence was applied	the hosted provider is configured and the served roles are verified

Refuses when:

• the relay refuses the pairing key — names the relay’s own reason
• the machine is already paired and its held licence cannot be applied — names the apply failure; the pairing is kept and no key is redeemed
• the relay answers no licence for this machine — names the relay’s answer and the control that retries
• the licence’s default model cannot take a verified chat turn — names the model and the verification that failed

contenox-cli license status

Read whether this machine is signed in, what its licence grants and which roles the grant serves.

service	license
operation	status
synopsis	contenox-cli license status

Reports the sign-in state of this machine: whether it is paired with the relay, whether a licence is held, the plan tier, the default and granted models with their capabilities, the origin inference is proxied through, when the licence expires, and the outcome of every inference role the last applied licence assigned. A machine that is not signed in, or whose licence the relay withdrew, answers the state with a refusal naming the control that fixes it.

Examples:

• contenox-cli license status — Read the sign-in state and the applied roles.

output
stdout	The sign-in state, the licence’s grants and the role outcomes.
format	text

status	when	meaning
0	the state was read	the report describes this machine’s licence

contenox-cli license usage

Read the metered usage of the account’s licence for the current window.

service	license
operation	usage
synopsis	contenox-cli license usage

Reads the account’s metered usage from the relay with this machine’s licence bearer: the window it covers, the tokens used against the plan’s allowance for every model and in total, this machine’s own share, and when the next allowance is minted. The allowance is the plan’s grant per machine and the ceiling is that grant across the entitled machines. A machine that is not signed in is refused and told to sign in.

Examples:

• contenox-cli license usage — Show used and allowed tokens per model and the next refill.

output
stdout	The window, the usage per model and the next refill.
format	text

status	when	meaning
0	the relay answered the usage	the figures are the ones the proxy enforces against

Refuses when:

• this machine is not paired — names the sign-in operation
• the relay refuses the licence bearer — names the relay’s answer and the sign-in operation

contenox-cli model capability set

Save model declaration

service	inference-model-registration
operation	register
synopsis	contenox-cli model capability set

Set a manual provider/model override.

The —think flag records whether this provider/model supports reasoning request controls, and —vision whether it accepts image input. Both are provider-level: they apply to every backend of that type. A flag you omit leaves its setting as it was.

—context, —max-output, —capabilities and the pricing flags are backend-level. Pass —backend to write them to one backend, or let them fan out to every backend of the given provider type. A capability list REPLACES the observed set rather than adding to it, so —capabilities states the whole set.

Pricing is USD per million tokens and is what the monthly spend ceiling is metered against: a model with no declared rate card costs nothing as far as the meter is concerned.

input	type	required	reached by	values
registration	object	yes	the operation’s request	—

output
stdout	The model identity and the facts now recorded for it.
format	text

status	when	meaning
0	the declaration is stored	every surface reading this connection sees the declared facts

Refuses when:

• the connection does not exist — names the connection and the command that lists them
• a capability list is scoped to one backend — refuses the partial scope rather than writing facts to a single backend

contenox-cli model capability set

Declare instructed code-completion support

service	instructed-code-completion
operation	declare
synopsis	contenox-cli model capability set

Declare which operation a provider model serves for code completion: the chat completion chain, or one bounded prompt operation using the model’s own fill-in-the-middle tokens. The declaration is recorded against the model, and assigning the model still requires the selected operation to run successfully.

input	type	required	reached by	values
provider	string	yes	the operation’s request	—
model	string	yes	the operation’s request	—
completionMode	string	yes	the operation’s request	instruct, prompt

output
stdout	The model identity and the completion mode now declared for it.
format	text

status	when	meaning
0	the mode is declared	the completion route resolves through the declared operation

Refuses when:

• the provider or model is not registered — names the connection and the command that lists its models
• the mode is not one this runtime serves — names the unsupported mode and the modes it accepts

contenox-cli setup

Install a native backend and prepare its local connection.

service	automatic-local-setup
operation	prepare-local
synopsis	contenox-cli setup

Run the setup wizard to pick an LLM provider (native modeld, Ollama local or Cloud, OpenAI, Anthropic, Gemini, Vertex AI, AWS Bedrock, or self-hosted vLLM), enter credentials, and set defaults. This is the same wizard that runs inside IDE terminals via ACP.

Examples: contenox-cli setup

input	type	required	reached by	values
nativePrerequisite	object	yes	the operation’s request	—

Examples:

• contenox-cli setup — The interactive journey.
• contenox-cli auto — The same installation driven from the machine’s own plan.

output
stdout	The wizard’s questions, then the defaults it saved.
stderr	The refusal when the run is not interactive.
format	text

status	when	meaning
0	the wizard completes or the operator quits	a quit keeps the current configuration

Refuses when:

• no input arrives because the run is not interactive — says the wizard is interactive, names errSetupNoInput, and points at ‘contenox-cli config set’ for a non-interactive run
• a store the settings name cannot be used — names the store and refuses before offering a wizard whose answers cannot be saved

contenox-cli usage

Describe local model usage inspection.

service	local-model-usage
operation	describe
synopsis	contenox-cli usage

Model calls made by this installation are recorded by model and may be inspected across the installation or within one conversation session.

output
stdout	The service description, then the operations this service exposes.
format	text

status	when	meaning
0	the description is rendered	nothing was changed

contenox-cli usage

List cumulative model usage.

service	local-model-usage
operation	list
synopsis	contenox-cli usage
flags	--session
options	—session selects one conversation

Cumulative totals per model, metered against the same rows the gateway reports. A call this installation did not record is absent rather than reported as zero.

input	type	required	reached by	values
sessionId	string	no	--session	—

output
stdout	One row per model with its cumulative token counts and metered cost.
format	table, or JSON when —json is given

status	when	meaning
0	the totals are rendered	an installation with no recorded calls reports no rows rather than an error

Refuses when:

• the local store cannot be opened — names the store that failed; recorded usage is never reported as no usage

Commands that reach no declared operation

These paths execute, and no declared operation reaches them yet, so nothing here documents them. Each is a capability waiting for its operation to be extracted and declared, or an adapter concern a contract cannot carry.

• contenox-cli acp
• contenox-cli acpx
• contenox-cli agent add
• contenox-cli agent check
• contenox-cli agent disable
• contenox-cli agent edit
• contenox-cli agent enable
• contenox-cli agent list
• contenox-cli agent remove
• contenox-cli agent show
• contenox-cli approvals list
• contenox-cli approvals respond
• contenox-cli autocomplete
• contenox-cli backend list
• contenox-cli backend login
• contenox-cli backend logout
• contenox-cli backend remove
• contenox-cli backend show
• contenox-cli beam
• contenox-cli chat
• contenox-cli config get
• contenox-cli config reset
• contenox-cli doctor
• contenox-cli events dispatch
• contenox-cli events firings
• contenox-cli events list
• contenox-cli events prune
• contenox-cli gateway
• contenox-cli gateway key
• contenox-cli gateway key create
• contenox-cli gateway key list
• contenox-cli gateway key revoke
• contenox-cli gateway serve
• contenox-cli gateway usage
• contenox-cli hitl trust
• contenox-cli inbox ack
• contenox-cli inbox list
• contenox-cli inbox show
• contenox-cli index
• contenox-cli init
• contenox-cli list
• contenox-cli mcp add
• contenox-cli mcp auth
• contenox-cli mcp list
• contenox-cli mcp remove
• contenox-cli mcp show
• contenox-cli mcp update
• contenox-cli mission bridge
• contenox-cli mission fire
• contenox-cli mission list
• contenox-cli mission plan
• contenox-cli mission reports
• contenox-cli mission show
• contenox-cli mission stop
• contenox-cli model
• contenox-cli model capability
• contenox-cli model capability show
• contenox-cli model capability unset
• contenox-cli model list
• contenox-cli model ps
• contenox-cli model pull
• contenox-cli model registry-list
• contenox-cli model set-context
• contenox-cli model show
• contenox-cli model stop
• contenox-cli modeld install
• contenox-cli modeld status
• contenox-cli ps
• contenox-cli pull
• contenox-cli run
• contenox-cli sandbox env
• contenox-cli session delete
• contenox-cli session fork
• contenox-cli session list
• contenox-cli session new
• contenox-cli session show
• contenox-cli session switch
• contenox-cli session workspaces
• contenox-cli shell-env list
• contenox-cli shell-env set
• contenox-cli shell-env unset
• contenox-cli show
• contenox-cli state clear
• contenox-cli state list
• contenox-cli state show
• contenox-cli stop
• contenox-cli tools add
• contenox-cli tools list
• contenox-cli tools remove
• contenox-cli tools show
• contenox-cli tools update
• contenox-cli update
• contenox-cli update check
• contenox-cli vet