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

Configure IM channels, schedule recurring cron jobs, install and reload plugins, and run admin operations from the Octop command line.

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 requires a running server.

List channels for an agent

octop channel list --agent main

​

Subcommands

Subcommand	Description
list	List all channels configured for an agent
get	Show the full configuration row for one channel
create	Create a new channel (interactive)
patch	Update an existing channel’s configuration
delete	Remove a channel
test	Instantiate the channel, start it, and stop it (requires running server)
config	Edit channel config offline
feishu-setup	Walk through the Feishu bot-creator flow step by step
bind	QR-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

octop cron list --agent main

​

Trigger formats

Pass any of the following values to --trigger:

Format	Example	Description
Cron expression	0 9 * * *	Standard five-field cron (minute hour day month weekday)
Interval	interval:3600	Fire every N seconds
One-shot date	date:2025-12-31T09:00:00	Fire once at an ISO 8601 datetime

​

Task type flag

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

--prompt is required and must be between 1 and 2000 characters. --name is optional; when omitted, the server derives a label from the prompt. octop cron run-now dispatches the job through the scheduler and therefore requires an active octop run process.

---

​

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

octop plugin list

​

Subcommands

Subcommand	Description
list	List all installed plugins
install	Install a plugin from a local path, ZIP, or Git URL
uninstall	Remove an installed plugin
reload	Reload 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).

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. All subcommands except login work offline.

List all users

octop user list

See Server Commands for details on octop user login, which attaches the CLI to a running server.

---

​

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)

octop admin overview

​

Subcommands

Subcommand	Description
overview	Show admin overview (user count, agent state distribution)
audit	Show audit log entries
providers	List and manage global (admin) providers
rotate-jwt-secret	Rotate the JWT secret directly via the local database

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

octop backup create

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. See Backup & Restore.