> 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: 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`.


```bash List channels for an agent
octop channel list --agent main
```
```bash Show one channel row
octop channel get --agent main <id>
```
```bash Create a channel interactively
octop channel create --agent main --kind telegram
```
```bash Update a channel's configuration
octop channel patch --agent main <id>
```
```bash Delete a channel
octop channel delete --agent main <id>
```
```bash Test a channel (instantiate → start → stop)
octop channel test --agent main <id>
```
```bash Edit channel config offline
octop channel config --agent main <id>
```
```bash Guided Feishu bot setup wizard
octop channel feishu-setup
```
```bash QR bind for QQ, WeCom, or Weixin
octop channel bind qq --agent main
octop channel bind wecom --agent main
octop channel bind weixin --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.


```bash List cron jobs for an agent
octop cron list --agent main
```
```bash Create a cron job
octop cron create --agent main --trigger '0 9 * * *' --prompt 'Morning briefing'
```
```bash Delete a cron job
octop cron delete --agent main <job_id>
```
```bash Trigger a job immediately
octop cron run-now --agent main <job_id>
```


### 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, then disable the job (row stays listed)       |

### 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 |


> **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.


```bash List installed plugins
octop plugin list
```
```bash Install from a local path
octop plugin install ./my-plugin
```
```bash Install from a Git repository
octop plugin install https://github.com/user/plugin.git
```
```bash Uninstall a plugin
octop plugin uninstall <name>
```
```bash Reload all plugins without restarting the server
octop plugin reload
```


### 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`).


> **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.


```bash List all users
octop user list
```
```bash Create a user
octop user create bob --password secret123
```
```bash Set or clear email
octop user set-email bob bob@example.com
octop user set-email bob --clear
```
```bash Set a user's role
octop user role bob admin
```
```bash Reset a user's password
octop user passwd <username> --password <password>
```
```bash Disable a user
octop user disable bob
```
```bash Delete a user
octop user delete bob --yes
```


***

## `octop admin`

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


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


### 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      |


> **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.


```bash Create a backup archive
octop backup create
```
```bash Restore from a backup archive
octop backup restore <archive>
```
```bash Show automatic backup settings
octop backup auto status
```
```bash Create one automatic backup now
octop backup auto run
```



> **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](/en/guide/guides/backup-restore.md).
> 

