Quickstart: Getting Started with the Octomind CLI Agent

Start in Two Commands

# Install
curl -fsSL https://octomind.run/install.sh | bash

# Start an interactive session in the current directory
octomind

The first command installs the binary. The second is equivalent to octomind run. On the first interactive launch, before any config exists, it asks where to get models:

Providers whose key is already in your environment are listed first. After you pick the main model, setup asks whether the supervisor and compression should use it too; answer n to choose a cheaper model for each. Esc on the first screen works like Skip.

Startup then resolves the default assistant:concierge tap agent. Run octomind configure to change providers or models later. Non-interactive runs (piped input, --format, --daemon) create the default config without prompting.

The first use of a tap agent fetches its manifest and dependencies, so it requires network access. Once the prompt appears, ask Octomind to inspect, explain, change, or verify the project in the directory where you started it.

Bring Your Own Key

The hub is optional. Run octomind configure, pick your provider, enter the key, and pick the models. See AI Providers to set the key and models by hand.

Try a First Task

Enter a request at the session prompt:

Explain how this project is structured and identify the best starting point for a new contributor.

Octomind can use the tools enabled for the active role. Inspect the current tools before requesting file edits, shell commands, or delegation; a tap's fetched manifest determines which capabilities are available:

/mcp

Essential Session Commands

For example, inspect a session, finish a task, and then exit:

/help
/info
/status
/done
/exit

See Sessions for model switching and image attachment examples.

Choose a Role or Tap Agent

The optional positional argument to octomind run is a tag:

• A plain name such as assistant selects a local [[roles]] entry.
• A category:variant tag such as developer:general resolves an agent from the configured taps.
• A domain name such as developer starts that domain's orchestrator (developer:chief) from the configured taps, unless a local role has the same name.

# Configured default tag
octomind

# Registry agent
octomind run developer:general

Plain names require a configured local role. See Roles for a complete local-role example and the Tap System for registry resolution.

Name and Resume Sessions

# Create a named session, or resume it when it already exists
octomind run --name my-feature

# Resume a named session
octomind run --resume my-feature

# Open the interactive recent-session picker
octomind run --resume

# Resume the most recent session for this working directory
octomind run --resume-recent

Run Non-Interactively

--format switches octomind run to stdin-driven operation. Use plain for text or jsonl for events. The positional argument is the agent tag, so pipe the prompt through stdin:

echo "Explain the authentication module" | \
  octomind run developer:general --format plain

echo "List TODO items" | \
  octomind run developer:general --format jsonl

Piped stdin also selects non-interactive operation without --format, using plain output. Empty stdin is an error.

Common Questions

Why does startup need network access? Tap resolution fetches agent definitions and may run dependency setup; model requests also need access to the selected provider. For a failed login on a headless machine:

octomind login --no-browser

Why does a command say no input was provided? A non-interactive run needs a nonempty stdin prompt:

printf '%s\n' 'Summarize this project.' | octomind run --format plain

See also

• Configuration — customize models, roles, tools, and limits
• AI Providers — choose OctoHub or configure provider credentials
• Sessions — manage interactive and persistent sessions
• MCP Tools — understand the tool surface