• English

      • Octop CLI: Channel, Cron, Plugin, and Admin Commands

      The CLI covers channel setup, cron scheduling, plugin management, and admin tasks alongside the web UI. Use these commands to wire up IM platforms, automate recurring prompts, extend Octop with plugins, and administer users — all from the terminal.

      octop channel

      Create and manage IM channel connections for an agent. Most subcommands work offline; test starts an embedded server and does not need a separate octop run.

      List channels for an agent
      Show one channel row
      Create a channel interactively
      Update a channel's configuration
      Delete a channel
      Test a channel (instantiate → start → stop)
      Edit channel config offline
      Guided Feishu bot setup wizard
      QR bind for QQ, WeCom, or Weixin
      List channels for an agent
      octop channel list --agent main

      Subcommands

      SubcommandDescription
      listList all channels configured for an agent
      getShow the full configuration row for one channel
      createCreate a new channel (interactive)
      patchUpdate an existing channel's configuration
      deleteRemove a channel
      testInstantiate the channel, start it, and stop it (requires running server)
      configEdit channel config offline
      feishu-setupWalk through the Feishu bot-creator flow step by step
      bindQR-code binding for QQ, WeCom, and Weixin (bind qq / bind wecom / bind weixin)

      octop cron

      Schedule recurring tasks that trigger agent prompts automatically. run-now requires a running server; all other subcommands work offline.

      List cron jobs for an agent
      Create a cron job
      Delete a cron job
      Trigger a job immediately
      List cron jobs for an agent
      octop cron list --agent main

      Trigger formats

      Pass any of the following values to --trigger:

      FormatExampleDescription
      Cron expression0 9 * * *Standard five-field cron (minute hour day month weekday)
      Intervalinterval:3600Fire every N seconds
      One-shot datedate:2025-12-31T09:00:00Fire once at an ISO 8601 datetime

      Task type flag

      --task-type valueBehaviour
      agent (default)The LLM processes the prompt and pushes its reply
      textThe prompt text is pushed verbatim, bypassing the LLM
      NOTE

      --prompt is required. The CLI has no --name. octop cron run-now boots an embedded server and does not need a separate octop run; newly created jobs still require a restart of a running octop run before the scheduler picks them up.

      octop plugin

      Install and manage third-party plugins. Plugins are dropped into ~/.octop/plugins/ and power the same plugin system used by the web UI.

      List installed plugins
      Install from a local path
      Install from a Git repository
      Uninstall a plugin
      Reload all plugins without restarting the server
      List installed plugins
      octop plugin list

      Subcommands

      SubcommandDescription
      listList all installed plugins
      installInstall a plugin from a local path, ZIP, or Git URL
      uninstallRemove an installed plugin
      reloadReload all plugins without restarting the server

      The web UI Plugins page can also install from a local ZIP and optionally overwrite a plugin of the same name. Bundled plugins ship with Octop disabled by default; uninstalling one does not recreate it on upgrade. Per-agent plugin toggles live under Personalization (GET/PUT /api/agents/{id}/tool-settings).

      TIP

      Use octop plugin reload after installing or updating a plugin to apply changes to a running server without a full restart.

      octop user

      Manage users in the local database. Every subcommand works offline. There is no octop user login: pin a default --user with octop config set-user, or pass --user on the subcommand.

      List all users
      Create a user
      Set or clear email
      Set a user's role
      Reset a user's password
      Disable a user
      Delete a user
      List all users
      octop user list

      octop admin

      Inspect system state, review the audit log, manage global providers, and perform administrative operations directly against the local database.

      Show admin overview (user count, agent state)
      Show audit log entries
      Show global (admin) providers
      Rotate the JWT secret
      Show admin overview (user count, agent state)
      octop admin overview

      Subcommands

      SubcommandDescription
      overviewShow admin overview (user count, agent state distribution)
      auditShow audit log entries
      providersList and manage global (admin) providers
      rotate-jwt-secretRotate the JWT secret directly via the local database
      WARNING

      octop admin rotate-jwt-secret writes a new JWT secret directly to the SQLite database. This immediately invalidates all active sessions — every logged-in user, including dashboard sessions and CLI tokens, will be signed out. Use this command intentionally, not routinely.

      octop backup

      Export and restore the full Octop state (database, workspaces, and configuration). All subcommands work fully offline.

      Create a backup archive
      Restore from a backup archive
      Show automatic backup settings
      Create one automatic backup now
      Create a backup archive
      octop backup create
      NOTE

      Automatic backups run inside octop run. Configure them in config.json → backup, with env overrides, or from Application Settings → Backup & Restore. Archives are named octop-auto-backup-*.tar.gz; retention never deletes manual octop-backup-* files. The web UI rejects concurrent backup or restore work while one operation is already running. See Backup & Restore.