Octop CLI: Agent, Chat, Skills, and Model Commands#

The CLI gives you full control over agents and conversations. Create agents from scratch or from bundled expert templates, start interactive chat sessions directly in the terminal, configure skills, manage LLM providers, and pick active models — all without opening the web UI.

#octop agent

Create, inspect, and control agent lifecycles. Most subcommands work without requiring octop run to be running.

octop agent create myagent

octop agent create analyst --persona-mbti INTJ

octop agent from-expert <expert_id>

octop agent list

octop agent start <agent_id>
octop agent stop <agent_id>
octop agent reload <agent_id>
octop agent delete <agent_id>

octop agent experts

#Subcommands

Run octop agent use <id> to write the agent ID into ~/.octop/cli_state.json. All subsequent commands that accept --agent will default to this value, saving you from repeating it.

#octop chats

Manage conversation threads and send messages. The repl and send subcommands start a temporary server process automatically — no separate octop run is needed.

octop chats repl

octop chats send --agent main 'Hello'

octop chats list --agent main

octop chats get --agent main <thread_id>

octop chats create --agent main

octop chats update --agent main <thread_id>

octop chats delete --agent main <thread_id>

#Subcommands

#octop skills

Enable or disable per-agent skills. These commands read and write the local skill library and do not need a running server.

octop skills list --agent main

octop skills enable weather --agent main

octop skills disable weather --agent main

octop skills config --agent main

#Subcommands

#octop models

Manage the model catalog, configure providers interactively, and pull Ollama models.

octop models config

octop models list

octop models active

octop models presets

octop models ollama-list

octop models ollama-pull llama3.2

octop models ollama-rm llama3.2

#Subcommands

#octop provider

Manage LLM provider records in the local database. The test subcommand requires a running server to make a live API call.

octop provider list

octop provider create

octop provider test

octop provider delete

#octop acp

Expose an Octop agent as a stdio JSON-RPC ACP server. Boots a standalone OctopServer (reads ~/.octop/); does not require octop run to be running.

octop acp

octop acp --agent myagent --debug

#Options

#Point your IDE at it

Configure octop acp as the ACP server command in your IDE. Zed example:

{
  "agent_servers": {
    "Octop": {
      "command": "octop",
      "args": ["acp", "--agent", "main"],
      "env": {}
    }
  }
}

{
  "agent_servers": {
    "Octop": {
      "command": "uv",
      "args": ["run", "octop", "acp", "--agent", "main"],
      "env": {}
    }
  }
}