CLI Reference

Complete reference for all `octomind` CLI commands and flags.

`octomind run [TAG] [MESSAGE]`

Start an interactive or non-interactive AI session.

Flag	Short	Description
`TAG`		Agent tag or role name (e.g., `developer`, `octomind:assistant`). Uses `default` from config if omitted.
`--name`	`-n`	Named session identifier
`--resume`	`-r`	Resume a specific session by name
`--resume-recent`		Resume the most recent session
`--format`		Output format: `plain` (default for pipe), `jsonl` (structured JSON Lines)
`--model`	`-m`	Override model (`provider:model` format)
`--daemon`		Daemon mode: stay alive after message, accept injected messages
`--sandbox`		Restrict filesystem writes to working directory
`--hook`		Activate webhook hook(s) by name. Can be specified multiple times.

Examples:

# Interactive session with default role
octomind run

# Interactive with specific role
octomind run developer

# Tap agent
octomind run octomind:developer

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

# Named session
octomind run --name feature-auth

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

# Daemon mode with webhook
octomind run --name ci-watcher --daemon --format jsonl --hook github-push

# Model override
octomind run -m anthropic:claude-sonnet-4

`octomind server [TAG]`

Start a WebSocket server for remote AI sessions.

Flag	Short	Description
`TAG`		Agent tag or role name
`--host`		Bind address (default: `127.0.0.1`)
`--port`	`-p`	Port (default: `8080`)
`--sandbox`		Restrict filesystem writes to working directory

Examples:

octomind server
octomind server --host 0.0.0.0 --port 9090
octomind server developer --sandbox

`octomind acp [TAG]`

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

Flag	Short	Description
`TAG`		Agent tag or role name
`--name`	`-n`	Session name (used when client creates a session)
`--resume`	`-r`	Resume a specific session by name
`--resume-recent`		Resume the most recent session
`--model`	`-m`	Override model (`provider:model` format)
`--sandbox`		Restrict filesystem writes to working directory
`--hook`		Activate webhook hook(s) by name. Can be specified multiple times.

Examples:

octomind acp developer
octomind acp context_gatherer --sandbox
octomind acp developer:general -m openai:gpt-4o

`octomind tap [TAP] [PATH]`

Add or list registry taps (Homebrew-style agent sources).

Argument	Description
`TAP`	Tap identifier (`user/repo` format). Omit to list all taps.
`PATH`	Optional local path. If provided, symlinks instead of cloning from GitHub.

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 untap <TAP>`

Remove a previously added tap.

octomind untap myorg/my-tap

`octomind vars`

Show all placeholder variables and their current values.

Flag	Short	Description
`--preview`	`-p`	Show preview of placeholder values (3 lines)
`--expand`	`-e`	Show full expanded values for placeholders

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

Displays: {{CWD}}, {{ROLE}}, {{DATE}}, {{SHELL}}, {{OS}}, {{BINARIES}}, {{GIT_STATUS}}, {{README}}, etc.

`octomind send`

Send a message to a running daemon session by name.

Flag	Short	Description
`--name`	`-n`	Name of the running session to send to (required)
`MESSAGE`		Message text. If omitted, reads from stdin.

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

`octomind config [OPTIONS]`

Generate, validate, or display configuration.

Flag	Description
`--model`	Set root-level model (`provider:model` format)
`--api-key`	Set API key (`provider:key` format)
`--log-level`	Set log level
`--mcp-providers`	Set MCP providers
`--mcp-server`	Add/configure MCP server
`--system`	Set custom system prompt (or `default` to reset)
`--markdown-enable`	Enable/disable markdown rendering
`--markdown-theme`	Set markdown theme
`--list-themes`	List available markdown themes
`--show`	Display current configuration with defaults
`--validate`	Validate configuration without making changes
`--upgrade`	Upgrade config file to latest version

Examples:

# Generate default config
octomind config

# Show current settings
octomind config --show

# Validate config
octomind config --validate

# List themes
octomind config --list-themes

`octomind completion <SHELL>`

Generate shell completion scripts.

Argument	Description
`SHELL`	Target shell: `bash`, `zsh`, `fish`, `powershell`, `elvish`

Shell	Command
Bash	`octomind completion bash > ~/.local/share/bash-completion/completions/octomind`
Zsh	`octomind completion zsh > ~/.zfunc/_octomind`
Fish	`octomind completion fish > ~/.config/fish/completions/octomind.fish`
PowerShell	`octomind completion powershell > octomind.ps1`

Global Flags

Flag	Description
`--help`	Show help
`--version`	Show version