• English

      • 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:

      OptionEnv varEffect
      --user TEXTOCTOP_USERDefault --user for admin subcommands (act on behalf of a user)
      --agent TEXTOCTOP_AGENTDefault --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.

      CommandDescription
      octop initBootstrap ~/.octop/ (DB, admin account, JWT secret)
      octop runStart the server in the foreground
      octop serviceManage the system service (systemd on Linux, launchd on macOS)
      octop agentCreate, list, start, stop, and reload agents
      octop chatsChat REPL and conversation session management
      octop channelIM channel setup and management
      octop cronScheduled task management
      octop providerLLM provider management
      octop modelsModel catalog and active model settings
      octop skillsEnable or disable per-agent skills
      octop acpExpose an agent as an ACP server (IDE integration)
      octop backupExport and restore backups
      octop userUser management
      octop adminAdmin operations (audit log, JWT rotation)
      octop captchaLogin captcha maintenance (reset clears a lockout from a misconfigured provider)
      octop pluginInstall and manage plugins
      octop updateCheck for and install updates
      octop cleanReset CLI state or wipe ~/.octop/
      octop configInspect and edit CLI state (pinned default user / agent)
      octop completionShell completion utilities
      octop versionPrint the installed octop version

      CLI State File

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

      {
  "default_user": null,
  "default_agent": null
}
      FieldDescription
      default_userPinned --user value (set via octop config set-user)
      default_agentPinned --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.