CLI Reference

Use this reference to launch sessions, configure Octomind, and automate workflows from your shell. It covers every CLI argument, including hidden internal commands.

Synopsis

octomind [COMMAND]
octomind COMMAND --help

Options belong after their subcommand; there are no inherited application options. Boolean switches default to false, optional values to unset, and repeatable options to an empty list unless stated otherwise.

The subcommand is optional. Bare octomind behaves as octomind run with the configured default tag.

The global config file lives at ~/.local/share/octomind/config/config.toml on macOS and Linux (%LOCALAPPDATA%\octomind\config\config.toml on Windows). Override the load path with OCTOMIND_CONFIG_PATH, or relocate the data tree with OCTOMIND_DATA_DIR. See Environment Variables for load/save path differences.

TAG resolution

run, server, and acp take an optional TAG:

• A role name (e.g. assistant) — matched against [[roles]] in your config.
• A registry agent tag in category:variant form (e.g. developer:general) — resolved through your installed taps.
• Omitted — uses the default tag from config.

Model resolution priority, highest first: explicit runtime override > role profile > tap name mapping > the required main [model].

Only run and workflow accept --format; neither restricts its value through clap. jsonl selects JSON Lines; other strings use the ordinary output path.

octomind login

Sign in through the browser-confirmed device flow and store the minted OctoHub key in Octomind's environment file.

octomind login
octomind login --force --no-browser

octomind config [OPTIONS]

Create, validate, display, or upgrade configuration. With no flags, see the example note below.

Loading happens before command dispatch and may create or migrate config even with --show or --validate.

Mutating flags (apply changes, then save to the loaded config path):

Inspect / maintenance flags:

Note on --api-key: the parser accepts an --api-key provider:key argument, but the mutation path rejects it at runtime — API keys can never be stored in the config file for security reasons. Set the provider's environment variable instead, using the credential example in Environment Variables. See Environment Variables for credential variables.

Inspection precedence is --list-themes, --show, --validate, then --upgrade; the first matching mode returns before mutations (including the --api-key rejection). Value options take one value. --markdown-enable requires true or false; --system default clears the legacy prompt.

octomind config --model octohub:auto --log-level debug
octomind config --markdown-enable true --markdown-theme dark
octomind config --system default
octomind config --mcp-providers core,runtime,orchestration,agent
octomind config --upgrade

--api-key PROVIDER:KEY has no short flag and takes one string; use environment credentials instead.

--mcp-server format

--mcp-server name,key=value,... — the first comma-separated token is the server name; the rest are key=value pairs:

# HTTP server
octomind config --mcp-server "search,url=http://localhost:9000,timeout=60"

# stdio server
octomind config --mcp-server "files,type=stdio,command=octofs"

Examples:

# Create a default config (only if none exists; otherwise reports
# the current state with no changes — it does NOT regenerate).
octomind config

# Show current settings
octomind config --show

# Validate config
octomind config --validate

# List themes
octomind config --list-themes

octomind run [TAG]

Start an interactive or non-interactive AI session.

Interactivity and --format: --format is unset by default. If it is omitted and stdin is a TTY, the session runs interactively. If --format is given (plain or jsonl) or stdin is piped, the session runs non-interactively, reading the input from stdin. Internally, an unset format resolves to plain.

run has no message argument: its only positional argument is TAG. With --format, a non-daemon run requires nonempty piped stdin; a TTY produces an error. Resuming without an explicit tag restores the saved role.

Daemon mode: --daemon keeps the session alive after a turn. Pair it with --format jsonl for a headless event stream. When attached to a TTY without --format, startup uses an empty initial input and the terminal stays interactive. Inject further messages with octomind send --name <name>.

Structured output (--schema): pass a path to a JSON Schema object file to constrain the model's output. The schema applies to every assistant reply for the session's lifetime — across multi-turn sessions, resumes, and daemon mode — while tool calls still flow normally underneath. If the resolved model reports no structured-output support, the run fails before the provider request. The schema is a runtime-only override and is not persisted, so pass it again when resuming. Most useful with --format jsonl. A ready-to-use example ships at config-templates/todos.schema.json.

Examples:

# Interactive session with the default tap agent
octomind run

# Explicit default tap agent
octomind run assistant:concierge

# Registry agent (category:variant)
octomind run developer:general

# Non-interactive: pipe message via stdin
echo "Explain the auth module" | octomind run assistant:concierge --format plain

# Named session
octomind run --name feature-auth

# Resume session
octomind run --resume feature-auth
octomind run --resume-recent

# Daemon mode with webhook
echo "Wait for build events" | octomind run --name ci-watcher --daemon --format jsonl --hook github-push

# Main-purpose model override
octomind run -m anthropic:claude-sonnet-4-6

# Structured output — constrain replies to a JSON Schema (structured-output models only)
echo "List the top 3 TODOs" | octomind run developer:general --format jsonl --schema config-templates/todos.schema.json

octomind server [TAG]

Start a WebSocket server for remote AI sessions.

Examples:

octomind server
octomind server --host 0.0.0.0 --port 9090
octomind server developer:general --sandbox
octomind server --allow-origin http://localhost:3000

octomind acp [TAG]

Run as Agent Client Protocol agent over stdio (for editor integration).

Examples:

octomind acp
octomind acp developer:general --sandbox
octomind acp assistant:concierge -m openai:gpt-5.6-luna

octomind tap [TAP] [PATH]

Add or list registry taps (Homebrew-style agent sources). Replace myorg/my-tap and the local path below with your own tap. myorg/my-tap resolves to the repository myorg/octomind-my-tap.

Examples:

# List all taps
octomind tap

# Add tap from GitHub
octomind tap myorg/my-tap

# Add local tap (symlink)
octomind tap myorg/my-tap /path/to/local/tap

octomind tap init <TAP>

Create a new tap repository from the default tap's scaffold (scaffolds/tap/ in muvon/octomind-tap). Renders the template, validates it, runs git init, and registers the directory as a local tap — the starter agent is runnable immediately.

Examples:

# Scaffold ./octomind-team, validate, git init, register as local tap
octomind tap init acme/team --agent team:assistant

# Then run the starter agent
octomind run team:assistant

# Custom starter agent and destination
octomind tap init acme/team --agent legal:contracts --dir ~/work/acme-tap

The destination must be missing or an empty directory. Rendering fails if any scaffold token remains unresolved or the validation command declared by the installed scaffold fails.

octomind untap <TAP>

Remove a previously added tap. TAP is required; use an identifier listed by octomind tap.

octomind untap myorg/my-tap

octomind vars

Show all placeholder variables and their current values.

With no flag, vars runs in list mode (names + descriptions). If both flags are given, --expand takes precedence over --preview.

octomind vars
octomind vars --preview
octomind vars --expand

Displays the placeholder set octomind vars reports: {{DATE}}, {{SHELL}}, {{OS}}, {{BINARIES}}, {{CWD}}, {{HOME}}, {{SYSTEM}} (complete system info), {{CONTEXT}} (README + git status + git tree), {{GIT_STATUS}}, {{GIT_TREE}}, and {{README}}. ({{ROLE}} is substituted in role prompts but is not among the values vars lists.)

octomind send

Inject a message into a running named session.

Works against any running session that has started its inject listener (typically a session launched with --daemon, but not exclusively). The message reaches the session over a per-OS transport:

• Unix: a Unix domain socket at <run_dir>/<stem>.sock (long names are shortened and suffixed with an eight-digit SHA-256 prefix) (run dir is $XDG_RUNTIME_DIR/octomind/, or <system tmp>/octomind-<uid>/ when that variable is unset).
• Windows: a named pipe \\.\pipe\octomind-<name>.

The session replies ok on successful delivery; any other reply is treated as an error and reported.

echo "Check build status" | octomind send --name ci-watcher
octomind send --name ci-watcher "Check build status"

octomind workflow [NAME|FILE]

Run a multi-step workflow defined in a TOML file.

Running a workflow reads input from stdin; listing workflows and --dry-run do not. Public tap workflows may reference only public tap roles; local files are not subject to that restriction. Per-step assistant responses, progress, cost, and token stats are written to stderr. When executing a target, stdout receives output only for --dry-run (the execution plan) or jsonl. Listing without a target also prints to stdout. With --format jsonl, stdout streams one {"type":"assistant","content":...,"step":"<name>","session_id":""} line as each step completes (the final result is simply the last one) followed by one {"type":"cost",...} line with aggregated tokens/cost. These are the same event shapes octomind run --format jsonl emits, with an extra step field identifying the originating step (omitted in run output). Workflows have no single resumable session, so session_id is empty. See Workflows.

Create myflow.toml in your working directory with this runnable one-step definition:

name = "refine"

[[steps]]
name = "refine"
role = "task_refiner"
prompt = "{{input}}"

octomind workflow
echo "build a JSON-to-CSV CLI in Rust" | octomind workflow myflow.toml
echo "build a JSON-to-CSV CLI in Rust" | octomind workflow myflow.toml --format jsonl
octomind workflow myflow.toml --dry-run

octomind completion <SHELL>

Generate shell completion scripts.

Create the destination directory before redirecting output. For Zsh:

mkdir -p ~/.zfunc
octomind completion zsh > ~/.zfunc/_octomind

Add ~/.zfunc to Zsh’s fpath before compinit in your shell configuration.

Dynamic agent-tag completion for octomind run <TAB> and tap-workflow completion for octomind workflow <TAB> are injected only into the bash, zsh, and fish scripts through the hidden complete helper. PowerShell and Elvish remain static.

Hidden internal commands

These commands are omitted from normal help but remain callable. complete reads cached tap data; an unknown subcommand prints nothing. distill reads and deletes its snapshot before parsing and extracting memories.

octomind complete run
octomind complete workflow
# A disposable empty snapshot demonstrates the input shape without inventing a transcript.
printf '[]\n' > /tmp/octomind-empty-transcript.json
octomind distill --messages /tmp/octomind-empty-transcript.json --role developer:general \
  --project demo --session demo --outcome unknown

Sandbox

When enabled, the sandbox restricts writes with Landlock on Linux or Seatbelt on macOS while retaining the state/temp exceptions defined by each backend. It is active if either the config sandbox setting or the --sandbox flag is set, and it applies only to run, server, and acp — all other subcommands ignore both. Other platforms log that the sandbox is unsupported.

octomind run developer:general --sandbox

Common questions

• Why does --format reject startup? Pipe a nonempty prompt; redirected empty stdin also fails in daemon mode.
• Why does bare --resume fail in a script? Supply a session name; the picker requires an interactive TTY.
• Why does send fail? The receiving session must still be running with its inject listener active. A saved session alone cannot receive messages.
• Why does a hook fail? --hook names must exist in [[hooks]]; see Daemon & Hooks for a complete hook configuration.

Help and version

octomind --version
octomind help tap init
octomind run --help

Source map

CLI registration: main.rs. Argument structs and behavior: run.rs, config.rs, server.rs, acp.rs, tap.rs, untap.rs, login.rs, send.rs, vars.rs, workflow.rs, complete.rs, distill.rs. Workflow file schema: schema.rs. State paths: directories.rs.

See also

• Session Commands
• Config Reference
• Environment Variables
• Workflows