> For AI agents: the complete documentation index is available at /en/llms.txt, the full documentation bundle is available at /en/llms-full.txt.

# Octop CLI Overview: All Commands and Transport Modes

The `octop` CLI is a single command installed alongside the server binary. Most commands work **offline** — reading and writing `~/.octop/` directly — so you can manage agents, users, channels, and cron jobs without a running server. A small number of commands (such as `chats repl` and `channel test`) start an embedded server automatically, or talk to an already running `octop run`.

## Global Options

Pass these flags before any subcommand to control output format and default targeting:

| Option          | Env var       | Effect                                                           |
| --------------- | ------------- | ---------------------------------------------------------------- |
| `--user TEXT`   | `OCTOP_USER`  | Default `--user` for admin subcommands (act on behalf of a user) |
| `--agent TEXT`  | `OCTOP_AGENT` | Default `--agent` for subcommands                                |
| `--json`        | —             | Emit machine-readable JSON output for list-style commands        |
| `-v, --version` | —             | Print the installed version and exit                             |

## Transport Modes

Every `octop` command selects one of three transports automatically based on what the operation requires:


**Offline**

Reads and writes `~/.octop/` directly. No running server is needed. Used by `init`, `backup`, `plugin`, `agent list`, `user *`, `admin overview/audit`, `captcha reset`, and most CRUD commands.

**Attach**

Connects to a running `octop run` process over HTTP. Used by `channel test`, `models ollama-*`, `provider test`, and similar commands. The CLI does **not** require a prior login: local filesystem access is enough. Pin the acting user with `octop config set-user`.

**Embedded**

Starts a temporary in-process server for a single command, then exits. No separate `octop run` needed. Used by `octop acp`, `octop chats repl`, `octop chats send`, and `octop agent create/from-expert/start/stop/reload`.

## Command Reference


> **TIP**
> 
> Run `octop --json` with any list command to get machine-readable JSON output — ideal for scripting and CI pipelines.
> 


| Command            | Description                                                                             |
| ------------------ | --------------------------------------------------------------------------------------- |
| `octop init`       | Bootstrap `~/.octop/` (DB, admin account, JWT secret)                                   |
| `octop run`        | Start the server in the foreground                                                      |
| `octop service`    | Manage the system service (systemd on Linux, launchd on macOS)                          |
| `octop agent`      | Create, list, start, stop, and reload agents                                            |
| `octop chats`      | Chat REPL and conversation session management                                           |
| `octop channel`    | IM channel setup and management                                                         |
| `octop bridge`     | Link another Octop instance (cloud collaboration)                                       |
| `octop cron`       | Scheduled task management                                                               |
| `octop provider`   | LLM provider management                                                                 |
| `octop models`     | Model catalog and active model settings                                                 |
| `octop skills`     | Enable or disable per-agent skills                                                      |
| `octop acp`        | Expose an agent as an ACP server (IDE integration)                                      |
| `octop backup`     | Export and restore backups                                                              |
| `octop migrate`    | Copy an OpenClaw or Hermes Agent setup into an expert                                   |
| `octop cloud`      | Import a local `tccli` login into the cloud-server page                                 |
| `octop user`       | User management                                                                         |
| `octop admin`      | Admin operations (audit log, JWT rotation)                                              |
| `octop captcha`    | Login captcha maintenance (`reset` clears a lockout from a misconfigured provider)      |
| `octop plugin`     | Install and manage plugins                                                              |
| `octop update`     | Check for and install updates                                                           |
| `octop clean`      | Reset CLI state, or delete Octop data under `~/.octop` while keeping `venv/` and `bin/` |
| `octop config`     | Inspect and edit CLI state (pinned default user / agent)                                |
| `octop completion` | Shell completion utilities                                                              |
| `octop version`    | Print the installed octop version                                                       |

## CLI State File

The file `~/.octop/cli_state.json` stores your CLI session state:

```json
{
  "default_user": null,
  "default_agent": null
}
```

| Field           | Description                                             |
| --------------- | ------------------------------------------------------- |
| `default_user`  | Pinned `--user` value (set via `octop config set-user`) |
| `default_agent` | Pinned `--agent` value (set via `octop agent use`)      |

Delete this file to clear CLI pins. The web UI and HTTP API clients manage their own tokens separately and do not share this file.


> **NOTE**
> 
> Override the location of `~/.octop/` by setting the `OCTOP_HOME` environment variable before running any `octop` command.
> 

