metabot CLI¶
metabot is the single MetaBot CLI binary. It has three command categories:
- Bridge process control — manage the local MetaBot service lifecycle.
- Bridge daemon API — curl the local bridge daemon at
localhost:9100. - metabot-core delegation — forward to the central feature CLI.
Installation¶
Installed automatically by the MetaBot installer to ~/.local/bin/metabot.
The legacy
mb/mm/mhCLIs have been removed. Install and update actively delete any leftover binaries from~/.local/bin/; if a script still calls them you'll seecommand not found— switch the call tometabot <subcommand>.
1. Bridge process control¶
metabot update # refresh from internal package, rebuild, update skills, restart
metabot update --git # developer-only: git pull + rebuild + restart
metabot start # start with PM2
metabot stop # stop
metabot restart # restart
metabot logs # view live logs (pass -n 100 etc.)
metabot status # PM2 process status
metabot update is the recommended way to update MetaBot. It performs:
- Download the current internal package from
METABOT_CORE_URL/install/latest.tgz - Overlay code files into
METABOT_HOME, preserving.env,bots.json,logs/,data/, and.git/ npm install && npm run build— rebuild- Copy bundled MetaBot skills into Claude/Codex skill directories
- If
lark-clior lark skills are already installed, update@larksuite/cliand refresh the lark AI Agent skills - Sync skills into the configured bot workspace
pm2 restart— restart the service
All in one command. Source checkouts can still use metabot update --git, but that is a developer-only path and requires a clean Git remote.
2. Bridge daemon API¶
These commands curl the local bridge daemon at localhost:9100, reading
API_PORT / API_SECRET (and optional METABOT_URL) from the bridge .env.
Bot management¶
Agent talk¶
metabot talk <bot> <chatId> <prompt> # talk to a bot (bridge /api/talk)
metabot talk alice/bot <chatId> <prompt> # talk to a specific peer's bot
The bot name supports qualified names
(peerName/botName) for cross-instance routing. This is the bridge-local talk
path; metabot agents talk is the separate central-registry P2P variant.
Peers¶
Agent Teams¶
metabot teams talks to the local bridge /api/agent-teams/* API. It is the coordination surface for MetaBot Agent Teams: agents, mailbox messages, shared tasks, and background runs.
metabot teams list
metabot teams create <team> [--description <text>]
metabot teams status <team>
metabot teams start <team>
metabot teams stop <team>
metabot teams delete <team>
metabot teams agents list <team>
metabot teams agents spawn <team> <name> [--role <role>] [--engine claude|codex|kimi] [--prompt <text>]
metabot teams agents stop <team> <name>
metabot teams agents delete <team> <name>
metabot teams send <team> <to> <message> [--from <name>] [--summary <text>]
metabot teams inbox <team> <name> [--unread] [--read]
metabot teams tasks list <team>
metabot teams tasks create <team> <subject> [--description <text>] [--owner <name>]
metabot teams tasks get <team> <id>
metabot teams tasks update <team> <id> [--status pending|in_progress|completed|deleted] [--owner <name>] [--result <text>]
metabot teams runs list <team>
metabot teams runs create <team> [--agent <name>] [--task-id <id>] [--status running|completed|failed|stopped] [--output <text>] [--error <text>]
metabot teams runs update <team> <runId> [--status running|completed|failed|stopped] [--output <text>] [--error <text>]
metabot teams runs output <team> <runId>
metabot teams runs stop <team> <runId>
runs stop marks the run stopped and, when the bridge supervisor owns the in-flight run, asks the bridge to stop that teammate chat task, requeues assigned in-progress tasks to pending, and suppresses late executor output for that stopped run.
The same command surface is implemented in both bin/metabot and the TypeScript feature CLI under packages/cli. The bridge reads API_PORT / API_SECRET and optional METABOT_URL from .env.
Scheduling¶
metabot schedule list # list all tasks
metabot schedule cron <bot> <chatId> '<cron>' <prompt> # create recurring task
metabot schedule add <bot> <chatId> <delaySec> <prompt> # create one-time task
metabot schedule pause <id> # pause a task
metabot schedule resume <id> # resume a task
metabot schedule cancel <id> # cancel a task
Stats, metrics & health¶
metabot stats # cost & usage statistics
metabot metrics # Prometheus metrics
metabot health # health check
Voice¶
metabot voice call <bot> <chatId> [prompt] [-w opening] # start an RTC voice call
metabot voice transcript <sessionId> # get call transcript
metabot voice list # list active voice sessions
metabot voice config # check RTC configuration
metabot voice tts "Hello world" # generate MP3, print file path
metabot voice tts "Hello" --play # generate and play audio
metabot voice tts "Hello" -o greeting.mp3 # save to specific file
echo "Long text" | metabot voice tts # read from stdin
metabot voice tts "Hello" --provider doubao # use specific TTS provider
metabot voice tts "Hello" --voice nova # use specific voice
TTS flags:
| Flag | Description |
|---|---|
--play |
Play audio after generating (macOS: afplay, Linux: mpv/ffplay/play) |
-o FILE |
Save to specific file (default: /tmp/metabot-voice-<timestamp>.mp3) |
--provider NAME |
TTS provider: doubao, openai, or elevenlabs |
--voice ID |
Voice/speaker ID (provider-specific) |
3. metabot-core delegation¶
Any subcommand not listed above is forwarded to the metabot-core feature CLI
(packages/cli/bin/metabot):
metabot t5t board # team standup board
metabot agents list # peer-bot directory
metabot memory search "<query>" # shared-memory full-text search
metabot skills list # central Skill Hub
METABOT_CORE_URL / METABOT_CORE_TOKEN are fed from the bridge .env when
not already exported. Override the CLI path with
export METABOT_CORE_CLI=/path/to/packages/cli/bin/metabot.
Remote Access¶
By default, the bridge daemon API connects to http://localhost:9100. For
internet-reachable deployments, point it at your HTTPS reverse proxy. If you use
a private network such as Tailscale or WireGuard, you can use that private
address instead.