v1.0 to v1.1

62 added, 59 removed. Audit A to A.

---

name: octomind-cli

title: "Octomind CLI & Session Commands"

- description: "Reference for driving the octomind binary: the run, server, acp, config, tap, vars, send, workflow, and completion commands and their flags, the 25 interactive slash commands, provider API-key environment variables, .env precedence, and OCTOMIND_* overrides. Activate when a user asks how to invoke octomind, which flag or slash command does what, how to resume or daemonize a session, or which environment variable a provider reads."

+ description: "Reference for driving the octomind binary: the run, server, acp, login, config, tap, untap, vars, send, evaluate, workflow, and completion commands and their flags, the interactive slash commands, provider API-key environment variables, .env precedence, and OCTOMIND_* overrides. Activate when a user asks how to invoke octomind, which flag or slash command does what, how to resume or daemonize a session, or which environment variable a provider reads."

license: Apache-2.0

compatibility: "Requires: octomind binary on PATH. macOS/Linux/Windows."

domains: octomind

rules:

- match((?i)\bslash command\b)

- semantic(which octomind command or flag do I use)

metadata:

- version: "1.0"

+ version: "1.1"

tags: "octomind cli session-commands environment"

---

## Overview

- This skill covers how to drive Octomind from the outside: the subcommands and flags of the `octomind` binary, the slash commands available inside a running session, and the environment variables that select providers and redirect state. It does not cover config file fields (see the `octomind-config` skill) or how manifests resolve (see `octomind-runtime`).

+ 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 the installed version first.

+ 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; some write to the session file (`/model`, `/effort`), some are runtime-only (`/loglevel`).

+ - 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

- A subcommand is required; bare `octomind` prints a usage error.

+ Bare `octomind` behaves like `octomind run` with the default role.

| Command | Purpose |

|---------|---------|

- | `run [TAG]` | Start an interactive or non-interactive session — the main command |

- | `server [TAG]` | WebSocket server for remote sessions (`--host`, `--port`, `--sandbox`) |

- | `acp [TAG]` | Agent Client Protocol agent over stdio, for editor integration |

+ | `run [TAG]` | Interactive or non-interactive session — the main command |

+ | `server [TAG]` | WebSocket server for remote sessions (`--host` default `127.0.0.1`, `--port`/`-p` default `8080`, `--sandbox`, repeatable `--allow-origin`) |

+ | `acp [TAG]` | Agent Client Protocol agent over stdio for editors (`-n`, `-r`, `--resume-recent`, `-m`, `--sandbox`, `--hook`) |

+ | `login [chatgpt]` | Sign in to an Octomind account (stores the hub key as `OCTOHUB_API_KEY`); `login chatgpt` lets `chatgpt:<model>` run on a ChatGPT plan |

| `config` | Create, validate, display, or upgrade configuration |

- | `tap [TAP] [PATH]` | Add a tap, or list taps when called bare |

+ | `tap [TAP] [PATH]` | Add a tap (`user/repo` clones `github.com/user/octomind-repo`; with PATH it links a local directory); bare lists taps |

+ | `tap init <user/repo>` | Scaffold a new tap from the default tap's scaffold, validate it, git-init it, register it (`--agent domain:spec`, `--dir`) |

| `untap <TAP>` | Remove a tap |

- | `vars` | Show placeholder variables and resolved values (`--preview`, `--expand`) |

- | `send` | Inject a message into a running named session |

- | `workflow` | Run an external multi-step pipeline TOML |

- | `completion <SHELL>` | Generate bash/zsh/fish completions |

+ | `vars` | Placeholder variables and resolved values (`-p/--preview`, `-e/--expand`) |

+ | `send --name <NAME> [MESSAGE]` | Inject a message into a running named session; message from stdin when omitted |

+ | `evaluate [FILE]` | Ask the evaluation model typed questions about a JSON state (`{"state", "questions"}` from FILE or stdin), answers printed as JSON; `-m` overrides the model |

+ | `workflow [NAME\|FILE]` | Run a multi-step workflow; bare lists tap workflows (`--dry-run`, `--format jsonl`) |

+ | `completion <SHELL>` | bash, zsh, fish, elvish, or powershell completions |

+ 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 `category:variant` form resolved through installed taps. Omitted, it uses `default` from config. Model priority, highest first: `--model` > the role/agent `model` field > root `config.model`; a `[taps]` entry overrides the `config.model` tier for tap agents only.

+ `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

| Flag | Effect |

|------|--------|

- | `--name` / `-n` | Named session identifier |

- | `--resume` / `-r` | Resume a session by name |

+ | `--name` / `-n` | Named session: created if new, resumed if it exists |

+ | `--resume` / `-r [SESSION]` | Resume by name; bare `--resume` opens the interactive picker (error when non-interactive) |

| `--resume-recent` | Resume the most recent session for this directory |

- | `--format` | `plain` or `jsonl`; unset by default |

+ | `--format` | `plain` or `jsonl`; setting it makes the run non-interactive |

| `--model` / `-m` | Override model, `provider:model` |

- | `--daemon` | Keep the session alive for injected messages |

+ | `--daemon` | Keep the session alive for messages delivered with `octomind send` |

| `--sandbox` | Restrict filesystem writes to the working directory |

- | `--hook` | Activate a webhook hook by name; repeatable |

- | `--schema` | Path to a JSON Schema object file constraining output |

+ | `--hook` | Activate a `[[hooks]]` webhook by name; repeatable |

+ | `--schema` | JSON Schema file constraining the final reply |

- Interactivity: with `--format` unset and stdin a TTY, the session is interactive. Passing `--format`, or piping stdin, makes it non-interactive. `--daemon` is non-interactive and effectively requires `--format`; deliver later messages with `octomind send --name <name>`.

+ 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` applies to every assistant reply for the session's lifetime, including resumes and daemon mode; tool calls still flow underneath and only the final text is constrained. Models without structured-output support fail fast. It is a runtime override, not persisted — pass it again on resume.

+ `--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 a,b,c` (replaces the whole server list with builtins), `--mcp-server name,key=value,...`, `--system` (`default` resets), `--markdown-enable`, `--markdown-theme`.

- Inspect only: `--show`, `--validate`, `--list-themes`, `--upgrade`.

- `--mcp-server` keys: `type` (`http`|`stdio`|`builtin`, default http), `url` (required for http), `command` (required for stdio), `args`, `timeout`/`timeout_seconds`.

+ 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`.

- `--api-key` parses but is always rejected at runtime. Keys live in the environment, never in config.

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

- Bare `octomind config` creates a default config only when none exists; it does not regenerate an existing one.

+ `--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

| Group | Commands |

|-------|----------|

- | Session | `/help`, `/exit` (`/quit`), `/clear`, `/list [PAGE]`, `/new [TITLE]` |

- | Monitoring | `/info`, `/report`, `/share`, `/analyze`, `/copy` |

+ | Session | `/help`, `/exit` (`/quit`), `/clear`, `/list [PAGE]`, `/new [TITLE]`, `/rename [TITLE]` |

| Media | `/image [PATH]`, `/video [PATH]` |

| Config-driven | `/run [COMMAND]`, `/prompt [NAME]` |

- | State | `/plan [show]`, `/schedule [SUBCOMMAND]`, `/learning [ACTION]` |

+ | Account | `/login` |

Behaviour worth knowing:

- - `/model` and `/effort` persist to the session file, not global config. `/loglevel` is runtime-only.

- - `/role` accepts a config role name or a tap tag; on failure the previous role, model, and temperature are reverted.

- - `/done` force-compresses context, bypassing threshold, cooldown, and cost guards, then triggers lesson extraction. It preserves no injected skills and does not touch the plan.

- - `/mcp` is read-only. Runtime server management is the `mcp` MCP tool, not the slash command.

- - `/plan` is display-only; the specialist has no plan mutation tool.

- - `/share` uploads the session JSONL and prints a permanent URL. `/analyze` uploads nothing — it binds a token-gated loopback bridge so the viewer fetches locally.

- - `/?` appears in autocomplete but is not wired to the dispatcher; only `/help` shows help.

+ - `/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

- Any provider prefix authenticates via its uppercased `<PREFIX>_API_KEY` — `groq:` reads `GROQ_API_KEY`. Common: `OPENROUTER_API_KEY` (recommended one-key entry point), `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, `OCTOHUB_API_KEY`.

- Providers needing more than one variable: Google Vertex (`GOOGLE_APPLICATION_CREDENTIALS` or `GOOGLE_CREDENTIAL_FILE`, plus `GOOGLE_CLOUD_PROJECT_ID`, `GOOGLE_CLOUD_LOCATION`), Amazon Bedrock (`AWS_BEARER_TOKEN_BEDROCK` — a Bedrock API key, not SigV4 credentials — plus `AWS_BEDROCK_REGION`), Cloudflare (`CLOUDFLARE_API_TOKEN` and the required `CLOUDFLARE_ACCOUNT_ID`).

+ 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.

- Most providers accept `<PREFIX>_API_URL` to target a self-hosted endpoint. The `cli:` meta-provider shells out to a local coding CLI and needs no key.

+ 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

| Variable | Effect |

|----------|--------|

- | `OCTOMIND_DATA_DIR` | Redirect all state: config, sessions, logs, cache, learning |

- | `OCTOMIND_CONFIG_PATH` | Override the config file path; its parent becomes the config dir for multi-file merge |

- | `OCTOMIND_SKILLS` | Comma-delimited skills preloaded at session start, bypassing activation rules |

- | `OCTOMIND_CAPABILITIES` | Comma-delimited capabilities force-enabled, bypassing auto-activation |

+ | `OCTOMIND_DATA_DIR` | Redirect durable state: config, sessions, logs, cache, learning, taps |

+ | `OCTOMIND_CONFIG_PATH` | Primary config file; its parent becomes the config dir for multi-file merge |

+ | `OCTOMIND_SKILLS` | Comma-separated exact skill names preloaded at session start |

+ | `OCTOMIND_CAPABILITIES` | Comma-separated capabilities force-enabled at start; domain and env gates still apply |

| `OCTOMIND_TELEMETRY` | `0`/`false`/`off`/`no` disables telemetry for the run |

| `DO_NOT_TRACK` | Cross-tool opt-out, honoured before `OCTOMIND_TELEMETRY` and config |

+ | `OCTOMIND_SHARE_URL` | Web viewer base for `/share` and `/analyze` |

| `RUST_LOG` | Tracing filter; in CLI mode it enables the stderr subscriber |

### .env precedence

- Two files load, later winning: user-scope `<config_dir>/.env`, then project-local `./.env`. Both override the system environment. An empty value counts as unset.

+ 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:

```bash

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

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

```

✅ Good:

```bash

- octomind run developer -m openai:gpt-4o

+ 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

```bash

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 and pairs naturally with `--schema`.

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

### Example 3: daemon plus webhook

```bash

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 — attached to a terminal, the piped input is forced empty.

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

## Checklist

- - [ ] Flag or slash command named exactly as it appears in the tables above?

+ - [ ] 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 `<PREFIX>_API_KEY` the provider reads?

+ - [ ] 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`