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

Create and manage agents, start interactive chat sessions, enable or disable skills, and configure LLM providers from the octop CLI.

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.

Create a basic agent

octop agent create --name myagent

​

Subcommands

Subcommand	Description
create	Create a new agent (accepts --user for admin cross-user creation)
from-expert	Create an agent from a bundled expert template
list	List all agents belonging to the current user
use <id>	Pin this agent as the default for subsequent commands
start	Start the agent runtime
stop	Stop the agent runtime
reload	Reload the agent runtime without deleting conversation history
delete	Delete the agent row, runtime, and workspace under ~/.octop/agents/<id>/ (permanent)
experts	List all bundled expert templates available on this install

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 agent delete permanently removes the agent workspace directory. The CLI asks for confirmation unless you pass --yes. This cannot be undone — back up first if you need the files.

---

​

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.

Start an interactive chat REPL

octop chats repl

​

Subcommands

Subcommand	Server required	Description
list	No	List conversation threads for an agent
get	No	Show message history for a thread
create	No	Start a new thread
update	No	Rename or pin a thread
delete	No	Delete a thread
send	Auto (embedded)	Send one message and stream the response
repl	Auto (embedded)	Interactive chat REPL

octop chats repl and octop chats send start a temporary in-process server for the duration of the command. You do not need to run octop run first. The list, get, create, update, and delete subcommands work fully offline against ~/.octop/octop.db.

The legacy command octop chat is a deprecated alias for octop chats. It still works but prints a warning — update your scripts to use octop chats instead.

---

​

octop skills

Enable or disable per-agent skills. All subcommands query the skill library at boot and require a running server.

List skills for an agent

octop skills list --agent main

​

Subcommands

Subcommand	Description
list	List skills for an agent
enable	Enable a skill for the agent
disable	Disable a skill for the agent
config	Show or edit the per-agent skills configuration

These commands require a running octop run process. They communicate with the live server to update the agent’s skill configuration. Start the server with octop run or octop service start before using octop skills enable or octop skills disable.

---

​

octop models

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

Interactive configuration wizard

octop models config

​

Subcommands

Subcommand	Server required	Description
config	No	Interactive wizard to create a provider and set the active model
list	No	List all models resolved across enabled providers
active	No	Show or set the global default model (admin)
presets	No	List built-in provider templates
ollama-list	Yes	List models available in a local Ollama instance
ollama-pull	Yes	Pull a model via Ollama
ollama-rm	Yes	Remove a local Ollama model

---

​

octop provider

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

List providers

octop provider list

octop provider list, create, and delete operate offline against ~/.octop/octop.db. Only octop provider test requires a running server, because it sends a live ping to the provider API.

---

​

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.

Expose the default agent

octop acp

​

Options

Option	Description
--agent TEXT	Agent to expose (default: OCTOP_AGENT or first agent)
--debug	Log to stderr

​

Point your IDE at it

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

~/.config/zed/settings.json

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

This is the reverse direction of the ACP runners guide: here your IDE drives an Octop agent, rather than an Octop agent delegating to a CLI tool.