Using the harness

CLI usage

Besides the interactive TUI, minima runs in two non-interactive modes and exposes two subcommands.

Usage

minima [prompt] [--print|--mode json] [options]
minima auth              sign in to Mubit + provision this repo's project
minima config [set|get]  manage stored credentials

Run modes

Mode	Invocation	Behavior
Interactive (default)	`minima`	Full Ink TUI. See Interactive TUI.
One-shot print	`minima -p "…"`	Runs the prompt, prints the final reply, exits.
Event stream	`minima --mode json "…"`	Streams agent events as JSON lines for scripting.

# one-shot
minima -p "explain this repo"
 
# machine-readable event stream
minima --mode json "refactor the config loader" | jq .

ℹ️Note

--print / --mode json require a prompt argument. Without one, the harness exits with an error.

Options

Flag	Argument	Meaning
`-p`, `--print`	—	One-shot: print the reply and exit.
`--mode`	`interactive` \| `print` \| `json`	Select the run mode explicitly.
`--model`	`ID`	Pin a model, bypassing routing.
`--provider`	`NAME`	Provider for a pinned `--model` (registers unknown models on the fly).
`--thinking`	`off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh`	Extended-thinking level for models that declare reasoning support (what actually reaches the model).
`--offline`	—	Bypass Minima routing entirely.
`-t`, `--tools`	`LIST`	Comma-separated tool allowlist (only these run).
`-xt`, `--exclude-tools`	`LIST`	Comma-separated tool denylist.
`-nt`, `--no-tools`	—	Disable all tools.
`-b`, `--budget`	`USD`	Session budget with graduated warnings at 50/75/90/100%.
`--budget-enforce`	—	Refuse new runs once the budget is exhausted (default: warn only).
`--slider`	`0–10`	Cost/quality tradeoff — 0 = cheapest acceptable, 10 = highest quality (default 5).
`-h`, `--help`	—	Print usage and exit.

# pin a specific model and raise thinking effort
minima --model claude-opus-4-8 --provider anthropic --thinking high -p "review this diff"
 
# read-only, no shell: allow only read/ls/grep
minima -t read,ls,grep -p "where is auth handled?"
 
# run without the recommender at all
minima --offline --model gpt-4o-mini --provider openai -p "quick summary"

💡Tip

--model (optionally with --provider) pins one model and skips routing; --offline skips the recommender while still using the seeded catalog. See Model routing for how these interact. Tool filtering with -t/-xt/-nt composes with the interactive permission system.

Thinking levels, and what reaches the model

The level you pick (--thinking, or ctrl+e in the TUI) is a request. What the provider actually sends is decided once, and the footer's reason: segment renders that same decision — so the indicator and the wire cannot disagree:

`reason:` shows	What is on the wire
`high`	The level was sent as asked.
`xhigh→high`	Sent, narrowed to what the host accepts. Hosts accept `low`/`medium`/`high` unless a model declares more, so `xhigh` and `minimal` normally narrow.
`high→none`	The model refuses an effort alongside function tools, so this turn pins it off. Tool-less calls keep the level.
`high→default`	Nothing was sent — the model has not declared reasoning support — so the model applies its own default.
`high→off`	The model declares it cannot reason at all.
hidden	Thinking is off and nothing is being overridden.

default is deliberately not off: a model whose server-side default is to reason will still reason when the harness sends nothing.

Reasoning support is registry data, per model — never inferred from a model id or a provider name. A model that declares nothing never receives the parameter, because some models reject it outright.

`minima auth`

Browser login → provisions a Mubit project for the current repo → stores MUBIT_API_KEY (and MINIMA_URL) → records the repo mapping in ~/.minima-harness/projects.json.

minima auth                 # default region
minima auth --region eu     # or --region us

The console URL defaults to https://console.mubit.ai (override with MUBIT_CONSOLE_URL).

`minima config`

Manage the per-user credential store without opening the TUI — works before any keys exist.

minima config                    # list every key (secrets masked)
minima config set MUBIT_API_KEY mbt_…
minima config get MINIMA_URL

See Configuration for every key, storage backend, and precedence rules.