octomind-cli

Overview

This skill covers how to drive Octomind from the outside: the subcommands and flags of the octomind binary, the slash commands inside a running session, and the environment variables that select providers and redirect state. Config file fields belong to the octomind-config skill; how manifests resolve belongs to octomind-runtime.

Answer from this reference rather than guessing flag names. When a user reports behaviour that contradicts it, check octomind --version and octomind <command> --help first — they are the ground truth.

Mental model

Three surfaces, three lifetimes:

• CLI flags — per invocation, never persisted (--model, --schema, --sandbox).
• Slash commands — per session; /model and /effort save to the session file, /loglevel is runtime-only.
• Config and environment — durable across sessions.

A change belongs on the narrowest surface that survives long enough. Never edit config for a one-off run.

Rules

Subcommands

Bare octomind behaves like octomind run with the default role.

Hidden helpers: octomind complete run prints every runnable tag (tap agents plus config roles), octomind complete workflow every tap workflow name — handy for scripting and discovery.

TAG resolution

run, server, and acp take an optional TAG: a plain role name matched against [[roles]] in config, or a tap agent tag in domain:spec form resolved through installed taps. Omitted, it uses default from config — except when resuming, where the session's own role is restored. Model priority, highest first: --model, the role's model, a [taps] entry for that tag, then the main [model] profile.

octomind run flags

Interactivity: with --format unset and stdin a TTY, the session is interactive. Otherwise input is read from stdin, and empty stdin is an error. --daemon is non-interactive and needs --format; attached to a terminal its initial input is empty.

--schema constrains the final reply for the session's lifetime; tool calls still flow underneath. Models without structured-output support fail fast. It is not persisted — pass it again on resume.

octomind config flags

Mutating (saved to the config file): --model, --log-level none|info|debug, --mcp-providers, --mcp-server name,url=X|command=Y,args=Z, --system (default resets), --markdown-enable, --markdown-theme.

Inspect or maintain: --show, --validate, --list-themes, --upgrade.

--api-key parses but is always rejected at runtime — keys live in the environment, never in config. Bare octomind config creates a default config only when none exists.

Session slash commands

Behaviour worth knowing:

• /model and /effort save to the session file, not global config. /loglevel is runtime-only.
• /role accepts a config role name or a tap tag.
• /done force-compresses context, bypassing threshold and cost guards, then starts lesson extraction in the background.
• /mcp is read-only. Runtime server management is the mcp tool of the runtime server.
• /plan only displays the supervisor-owned plan; nothing in the session can edit it.
• /workflow lists tap workflows, /workflow <name> shows the definition, /workflow <name> <input> runs it (blocking).
• /share uploads the session and prints a URL. /analyze uploads nothing — it serves a token-gated local bridge for the web viewer.
• /? shows in autocomplete but is not dispatched; use /help.

Provider environment variables

Most providers read <PREFIX>_API_KEY for their model prefix — groq: reads GROQ_API_KEY, openrouter: reads OPENROUTER_API_KEY. It is a per-provider contract, not a universal rule. Exceptions worth knowing: google-vertex: uses GOOGLE_VERTEX_CREDENTIAL_FILE (or GOOGLE_APPLICATION_CREDENTIALS) plus optional GOOGLE_VERTEX_PROJECT_ID/GOOGLE_VERTEX_LOCATION; amazon: uses AWS_BEARER_TOKEN_BEDROCK (a Bedrock API key, not SigV4 keys) plus AWS_BEDROCK_REGION; cloudflare: needs CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID; moonshot:/kimi: share MOONSHOT_API_KEY; opencode-zen:/opencode-go: share OPENCODE_API_KEY; octohub: reads OCTOHUB_API_KEY, which octomind login writes.

Many providers accept a <PREFIX>_API_URL endpoint override; local: with LOCAL_API_URL targets any self-hosted OpenAI-compatible server. The cli:BACKEND/MODEL meta-provider runs an installed coding CLI and needs no key.

Octomind environment variables

.env precedence

Two files load, later winning: user-scope <config_dir>/.env, then project-local ./.env. Both override the system environment.

Examples

Example 1: one-off model change

❌ Bad:

octomind config --model openai:gpt-5   # rewrites global config for one task

✅ Good:

octomind run developer:general -m openai:gpt-5

What changed: the narrowest surface that survives long enough — a flag, not a persisted setting.

Example 2: non-interactive with structured output

echo "List the top 3 TODOs" | octomind run developer:general \
  --format jsonl --schema todos.schema.json

Piped stdin already forces non-interactive mode; --format jsonl makes the stream machine-readable.

Example 3: daemon plus webhook

octomind run --name ci-watcher --daemon --format jsonl --hook github-push
echo "status?" | octomind send --name ci-watcher

--daemon without --format is the common mistake.

Checklist

• Flag or slash command named exactly as --help and the tables above show?
• One-off change expressed as a CLI flag rather than a config edit?
• --daemon paired with --format and a --name?
• API key set via environment or .env, never suggested for config.toml?
• Provider variable is the exact name that provider reads, including the documented exceptions?
• Session-scoped answers use slash commands; durable ones route to octomind-config?

Composition / References

• Pairs with octomind-config for anything inside config.toml.
• Pairs with octomind-runtime for how a TAG resolves to a manifest.
• Octomind docs: doc/reference/01-cli-reference.md, doc/reference/02-session-commands.md, doc/reference/04-environment-variables.md