> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash List channels for an agent theme={null}
octop channel list --agent main
```

```bash Show one channel row theme={null}
octop channel get --agent main <id>
```

```bash Create a channel interactively theme={null}
octop channel create --agent main
```

```bash Update a channel's configuration theme={null}
octop channel patch --agent main <id>
```

```bash Delete a channel theme={null}
octop channel delete --agent main <id>
```

```bash Test a channel (instantiate → start → stop) theme={null}
octop channel test --agent main <id>
```

```bash Edit channel config offline theme={null}
octop channel config --agent main <id>
```

```bash Guided Feishu bot setup wizard theme={null}
octop channel feishu-setup
```

```bash QR bind for QQ, WeCom, or Weixin theme={null}
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 theme={null}
octop cron list --agent main
```

```bash Create a cron job theme={null}
octop cron create --agent main --name 'Morning briefing' --trigger '0 9 * * *' --prompt 'Morning briefing'
```

```bash Delete a cron job theme={null}
octop cron delete --agent main <job_id>
```

```bash Trigger a job immediately theme={null}
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 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 |

> [!NOTE]
>
> `--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.

```bash List installed plugins theme={null}
octop plugin list
```

```bash Install from a local path theme={null}
octop plugin install ./my-plugin
```

```bash Install from a Git repository theme={null}
octop plugin install https://github.com/user/plugin.git
```

```bash Uninstall a plugin theme={null}
octop plugin uninstall <name>
```

```bash Reload all plugins without restarting the server theme={null}
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. All subcommands except `login` work offline.

```bash List all users theme={null}
octop user list
```

```bash Create a user theme={null}
octop user create --username bob --password secret123
```

```bash Set a user's role theme={null}
octop user role --username bob --role admin
```

```bash Reset a user's password theme={null}
octop user passwd --username bob
```

```bash Disable a user theme={null}
octop user disable --username bob
```

```bash Delete a user theme={null}
octop user delete --username bob
```

See [Server Commands](https://octop.mintlify.site/cli/server-commands.md#octop-user-login) 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.

```bash Show admin overview (user count, agent state) theme={null}
octop admin overview
```

```bash Show audit log entries theme={null}
octop admin audit
```

```bash Show global (admin) providers theme={null}
octop admin providers
```

```bash Rotate the JWT secret theme={null}
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 theme={null}
octop backup create
```

```bash Restore from a backup archive theme={null}
octop backup restore <archive>
```

```bash Show automatic backup settings theme={null}
octop backup auto status
```

```bash Create one automatic backup now theme={null}
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. See [Backup & Restore](https://octop.mintlify.site/guides/backup-restore.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.