CLI Reference
Complete reference for the openbee ctl command-line tool
The openbee ctl command is the command-line interface for controlling a running openbee server. All subcommands communicate with the local server over its configured API.
Global Flag
| Flag | Type | Default | Description |
|---|---|---|---|
--config, -c | string | config.yaml | Path to config file |
worker
Manage worker agents.
worker list
List all registered workers with optional filtering and pagination.
openbee ctl worker list [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--department | string | No | Filter by department ID or name |
--no-recursive | bool | No | Only return workers directly in the department (not in child departments) |
--name | string | No | Filter by name (case-insensitive partial match) |
--id | string | No | Filter by exact worker ID |
--page | int | No | Page number (default: 1) |
--page-size | int | No | Page size (default: 50, max: 200) |
worker get
Get a worker by ID.
openbee ctl worker get <id>| Argument | Required | Description |
|---|---|---|
id | Yes | Worker UUID |
worker status
Get current status of a worker.
openbee ctl worker status <id>| Argument | Required | Description |
|---|---|---|
id | Yes | Worker UUID |
worker create
Create a new worker.
openbee ctl worker create --name <name> [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--name, -n | string | Yes | Worker name |
--description | string | No | Worker description |
--constraints | string | No | Worker constraints content |
--work-dir | string | No | Working directory path |
--engine | string | No | AI engine to use (e.g. claude, codex, pi, kimi); leave empty for server default |
--department | string | No | Department ID or name (comma-separated for multiple) |
--scopes | string | No | Permission scopes (comma-separated, e.g. read:workers,read:tasks) |
--engine-args | string | No | Extra CLI args per engine, e.g. "claude=--model claude-sonnet-4-6" (repeatable) |
worker update
Update a worker's properties (patch semantics: omitted fields are unchanged).
openbee ctl worker update <id> [flags]| Argument / Flag | Type | Required | Description |
|---|---|---|---|
id | — | Yes | Worker UUID |
--name | string | No | New name |
--description | string | No | New description |
--constraints | string | No | New constraints content |
--engine | string | No | AI engine to use (e.g. claude, codex, pi, kimi); leave empty to keep unchanged |
--department | string | No | Department ID or name (comma-separated); replaces all associations. Pass empty string to clear |
--scopes | string | No | Permission scopes (comma-separated); replaces all scopes. Pass empty string to clear |
--engine-args | string | No | Extra CLI args per engine (repeatable); pass "claude=" to clear |
worker delete
Delete a worker.
openbee ctl worker delete <id> [--delete-work-dir]| Argument / Flag | Type | Required | Description |
|---|---|---|---|
id | — | Yes | Worker UUID |
--delete-work-dir | bool | No | Also delete the working directory from disk |
task
Manage tasks.
task list
List tasks. At least one of --session-key, --message-id, or --worker-id is required.
openbee ctl task list [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--session-key | string | Conditional | Filter by session key (mutually exclusive with --message-id) |
--message-id | string | Conditional | Filter by message ID (mutually exclusive with --session-key) |
--worker-id | string | Conditional | Filter by worker ID |
--status | string | No | Filter by status, comma-separated (e.g. pending,running) |
--type | string | No | Filter by type, comma-separated (e.g. immediate,countdown) |
task create
Create a task and assign it directly to a worker, bypassing the Bee's automatic routing.
openbee ctl task create --message-id <id> --worker-id <id> --instruction <text> --type <type> [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--message-id | string | Yes | ID of the originating platform message |
--worker-id | string | Yes | Worker UUID to assign |
--instruction | string | Yes | Instruction for the worker |
--type | string | Yes | Task type: immediate, countdown, or scheduled |
--scheduled-at | int64 | Conditional | Unix milliseconds; required for countdown (must be ≥ now + 5s) |
--cron | string | Conditional | 5-field cron expression; required for scheduled |
Examples
# Immediate task — executes as soon as the worker is available
openbee ctl task create \
--message-id "msg-abc123" \
--worker-id "worker-uuid" \
--instruction "Analyze the latest deployment logs and report any errors" \
--type immediate
# Countdown task — executes at a specific time (Unix milliseconds, must be ≥ now + 5s)
openbee ctl task create \
--message-id "msg-abc123" \
--worker-id "worker-uuid" \
--instruction "Send the end-of-day summary report" \
--type countdown \
--scheduled-at 1735660800000
# Scheduled task — executes on a recurring cron schedule
openbee ctl task create \
--message-id "msg-abc123" \
--worker-id "worker-uuid" \
--instruction "Check system health and alert if any service is down" \
--type scheduled \
--cron "0 * * * *"If --cron is invalid, the task is created with status cancelled and a reason field explaining the parse error.
task cancel
Cancel a pending or scheduled task.
openbee ctl task cancel <id>| Argument | Required | Description |
|---|---|---|
id | Yes | Task UUID |
memory
Manage persistent memory entries.
memory get
Read memory entries. Omit --key to list all entries in a scope.
openbee ctl memory get --scope <scope> [--key <key>]| Flag | Type | Required | Description |
|---|---|---|---|
--scope | string | Yes | global or a session key |
--key | string | No | Memory key; omit to return all entries in scope |
memory save
Save or update a memory entry.
openbee ctl memory save --scope <scope> --key <key> --value <value>| Flag | Type | Required | Description |
|---|---|---|---|
--scope | string | Yes | global or a session key |
--key | string | Yes | Memory key |
--value | string | Yes | Memory value |
memory delete
Delete a memory entry.
openbee ctl memory delete --scope <scope> --key <key>| Flag | Type | Required | Description |
|---|---|---|---|
--scope | string | Yes | global or a session key |
--key | string | Yes | Memory key |
session
Manage session contexts.
session list
List all workers with active session contexts for a session key.
openbee ctl session list --session-key <key>| Flag | Type | Required | Description |
|---|---|---|---|
--session-key | string | Yes | Session key to query |
session clear
Cancel all active tasks and clear all session contexts for a session key.
openbee ctl session clear --session-key <key> [--force]| Flag | Type | Required | Description |
|---|---|---|---|
--session-key | string | Yes | Session key to clear |
--force | bool | No | Skip confirmation when multiple workers are linked |
session clear-worker
Reset one worker's session context within a session.
openbee ctl session clear-worker --session-key <key> --worker-id <id>| Flag | Type | Required | Description |
|---|---|---|---|
--session-key | string | Yes | Session key |
--worker-id | string | Yes | Worker UUID whose session context to reset |
execution
Query worker execution records.
execution list
List worker execution records with optional filtering and pagination.
openbee ctl execution list [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--worker-id | string | No | Filter by worker ID |
--session-id | string | No | Filter by session ID |
--status | string | No | Filter by status (pending, running, completed, failed) |
--started-from | int64 | No | Filter started_at >= value (Unix ms) |
--started-to | int64 | No | Filter started_at <= value (Unix ms) |
--completed-from | int64 | No | Filter completed_at >= value (Unix ms) |
--completed-to | int64 | No | Filter completed_at <= value (Unix ms) |
--page | int | No | Page number (default: 1) |
--page-size | int | No | Page size (default: 50, max: 100) |
department
Manage departments. Workers can be organized into departments for filtering and access control.
department list
List all departments as a tree structure.
openbee ctl department listdepartment get
Get a department by ID or name.
openbee ctl department get <id|name>| Argument | Required | Description |
|---|---|---|
id|name | Yes | Department ID or name |
department create
Create a new department.
openbee ctl department create --name <name> [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--name, -n | string | Yes | Department name |
--parent | string | No | Parent department ID or name |
--sort-order | int | No | Display sort order |
department update
Update a department's properties (patch semantics: omitted fields are unchanged).
openbee ctl department update <id|name> [flags]| Argument / Flag | Type | Required | Description |
|---|---|---|---|
id|name | — | Yes | Department ID or name |
--name | string | No | New name |
--parent | string | No | New parent department ID or name |
--sort-order | int | No | New sort order |
department delete
Delete a department.
openbee ctl department delete <id|name>| Argument | Required | Description |
|---|---|---|
id|name | Yes | Department ID or name |
system
View system status and execution history.
system overview
Show system-wide statistics: worker status distribution, task counts, and recent executions.
openbee ctl system overviewsystem executions
List bee coordinator execution history.
openbee ctl system executions [--limit <n>]| Flag | Type | Required | Description |
|---|---|---|---|
--limit | int | No | Number of records to return (default: 10) |
message
Send and query platform messages.
message send
Send a message to the user on the originating platform. Supports plain text (via stdin), media files, or both. To send multiple files, call message send once per file.
openbee ctl message send --message-id <id> [--stdin] [--media-path <path>]| Flag | Type | Required | Description |
|---|---|---|---|
--message-id | string | Yes | ID of the originating platform message |
--stdin | bool | No | Read text content from stdin (use with heredoc) |
--media-path | string | No | Local file path to upload and send as media |
At least one of --stdin or --media-path must be provided.
Examples
# Send plain text via heredoc
openbee ctl message send --message-id <id> --stdin << 'EOF'
Task complete.
EOF
# Send a file
openbee ctl message send --message-id <id> --media-path /tmp/report.pdf
# Send text and file together
openbee ctl message send --message-id <id> --stdin --media-path /tmp/report.pdf << 'EOF'
Report attached.
EOFmessage list
List received (inbound) platform messages with optional filtering and pagination.
openbee ctl message list [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--session-key | string | No | Filter by session key |
--platform | string | No | Filter by platform (e.g. feishu, local) |
--status | string | No | Filter by status (received, feeding, bee_processed, merged, failed) |
--received-from | int64 | No | Filter received_at >= value (Unix ms) |
--received-to | int64 | No | Filter received_at <= value (Unix ms) |
--page | int | No | Page number (default: 1) |
--page-size | int | No | Page size (default: 50, max: 100) |
message list-outbound
List sent (outbound) platform messages with optional filtering and pagination.
openbee ctl message list-outbound [flags]| Flag | Type | Required | Description |
|---|---|---|---|
--session-key | string | No | Filter by session key |
--platform | string | No | Filter by platform (e.g. feishu, local) |
--status | string | No | Filter by status (sent, failed) |
--source-type | string | No | Filter by source type (bee, worker, system) |
--source-id | string | No | Filter by source ID |
--sent-from | int64 | No | Filter sent_at >= value (Unix ms) |
--sent-to | int64 | No | Filter sent_at <= value (Unix ms) |
--page | int | No | Page number (default: 1) |
--page-size | int | No | Page size (default: 50, max: 100) |