title: CLI Reference description: Current command-line reference for SwarmClaw

CLI Reference

SwarmClaw includes a built-in CLI for setup and day-to-day operations.

Installation

cd swarmclaw
npm run cli -- --help

# or run directly
node ./bin/swarmclaw.js --help

Usage

swarmclaw [global-options] <group> <command> [command-options]

Routing note: swarmclaw uses a hybrid router. Some legacy rich commands still use -u/--url, -k/--key, and --raw; mapped API commands use the options below.

Global Options

Command Groups

Use swarmclaw <group> --help for full per-command options.

agents

swarmclaw agents list
swarmclaw agents get <agentId>

tasks

swarmclaw tasks list
swarmclaw tasks get <taskId>
swarmclaw tasks create --title "Fix flaky test" --agent-id <agentId>
swarmclaw tasks update <taskId> --status running
swarmclaw tasks delete <taskId>
swarmclaw tasks archive <taskId>
swarmclaw tasks import-github --data '{"repo":"owner/repo","state":"open","limit":25}'

schedules

swarmclaw schedules list
swarmclaw schedules get <scheduleId>
swarmclaw schedules create --name "Daily report" --agent-id <agentId> --task-prompt "Generate report" --schedule-type cron --cron "0 9 * * *"

runs

swarmclaw runs list --session-id <sessionId>
swarmclaw runs get <runId>

chats

swarmclaw chats list
swarmclaw chats get <chatId>
swarmclaw chats create --name "Main Ops" --agent-id <agentId>
swarmclaw chats update <chatId> --heartbeat-enabled true --heartbeat-interval-sec 60
swarmclaw chats messages <chatId>
swarmclaw chats chat <chatId> --data '{"text":"Status update?"}'
swarmclaw chats mailbox <chatId>
swarmclaw chats stop <chatId>
swarmclaw chats delete <chatId>

sessions is a legacy alias in some compatibility paths, but chats is the canonical command group.

chatrooms

swarmclaw chatrooms list
swarmclaw chatrooms create --data '{"name":"Ops Room","agentIds":["agent-1","agent-2"]}'
swarmclaw chatrooms chat <chatroomId> --data '{"text":"@all status update?"}'
swarmclaw chatrooms react <chatroomId> --data '{"messageId":"<messageId>","emoji":"👍"}'
swarmclaw chatrooms pin <chatroomId> --data '{"messageId":"<messageId>"}'
swarmclaw chatrooms add-member <chatroomId> --data '{"agentId":"agent-3"}'
swarmclaw chatrooms remove-member <chatroomId> --data '{"agentId":"agent-3"}'

memory

swarmclaw memory list --query q="deployment checklist"
swarmclaw memory create --data '{"title":"Deploy note","content":"Remember to rotate keys","category":"note","agentId":"<agentId>"}'
swarmclaw memory maintenance
swarmclaw memory maintenance-run --data '{"ttlHours":24,"maxDeletes":100}'

memory-images

swarmclaw memory-images get <filename>

setup

# Interactive setup (walks through provider selection, supports adding multiple providers)
swarmclaw setup init

# Non-interactive setup with flags
swarmclaw setup init --provider openai --api-key "$OPENAI_API_KEY"

# Force non-interactive mode
swarmclaw setup init --provider google --api-key "$GOOGLE_API_KEY" --no-interactive

swarmclaw setup check-provider --provider ollama --endpoint http://localhost:11434
swarmclaw setup doctor
swarmclaw setup openclaw-device

gateways

swarmclaw gateways list
swarmclaw gateways create --data '{"name":"Local OpenClaw","endpoint":"http://localhost:18789/v1","isDefault":true}'
swarmclaw gateways health <gatewayId>
swarmclaw gateways update <gatewayId> --data '{"credentialId":"<credentialId>"}'
swarmclaw gateways delete <gatewayId>

external-agents

swarmclaw external-agents list
swarmclaw external-agents create --data '{"name":"Remote Builder","sourceType":"openclaw","status":"online","agentId":"<agentId>","endpoint":"https://example-gateway/v1","capabilities":["code","web"]}'
swarmclaw external-agents heartbeat <runtimeId> --data '{"status":"online","tokenStats":{"input":1200,"output":240}}'
swarmclaw external-agents update <runtimeId> --data '{"labels":["prod","builder"]}'
swarmclaw external-agents delete <runtimeId>

openclaw

swarmclaw openclaw discover
swarmclaw openclaw deploy-status
swarmclaw openclaw deploy-local-start --data '{"port":18789}'
swarmclaw openclaw deploy-local-restart --data '{"port":18789}'
swarmclaw openclaw deploy-local-stop
swarmclaw openclaw deploy-bundle --data '{"template":"docker","provider":"hetzner","target":"openclaw.example.com"}'
swarmclaw openclaw deploy-ssh --data '{"target":"openclaw.example.com","provider":"hetzner","ssh":{"host":"your-vps-ip"}}'
swarmclaw openclaw deploy-verify --data '{"endpoint":"https://openclaw.example.com/v1"}'
swarmclaw openclaw remote-start --data '{"ssh":{"host":"your-vps-ip"}}'
swarmclaw openclaw remote-stop --data '{"ssh":{"host":"your-vps-ip"}}'
swarmclaw openclaw remote-restart --data '{"ssh":{"host":"your-vps-ip"}}'
swarmclaw openclaw remote-upgrade --data '{"ssh":{"host":"your-vps-ip"}}'
swarmclaw openclaw remote-backup --data '{"ssh":{"host":"your-vps-ip"}}'
swarmclaw openclaw remote-restore --data '{"backupPath":"/opt/openclaw/backups/openclaw-backup-123.tgz","ssh":{"host":"your-vps-ip"}}'
swarmclaw openclaw remote-rotate-token --data '{"ssh":{"host":"your-vps-ip"}}'
swarmclaw openclaw gateway-status
swarmclaw openclaw gateway --data '{"action":"connect"}'
swarmclaw openclaw config-sync
swarmclaw openclaw dotenv-keys
swarmclaw openclaw doctor

deploy-bundle returns the generated files, runbook steps, endpoint, and token. deploy-ssh starts the same official-image bundle over SSH on your own host. Docker/VPS bundles include cloud-init.yaml for providers such as Hetzner, DigitalOcean, Vultr, Linode, Lightsail, GCP, Azure, OCI, and generic Ubuntu hosts.

remote-* commands operate on SSH-managed OpenClaw hosts and cover start, stop, restart, upgrade, backup, restore, and token rotation.

connectors

swarmclaw connectors list
swarmclaw connectors get <connectorId>
swarmclaw connectors create --platform telegram --agent-id <agentId> --name "Team Telegram"
swarmclaw connectors update <connectorId> --enabled
swarmclaw connectors start <connectorId>
swarmclaw connectors stop <connectorId>
swarmclaw connectors repair <connectorId>
swarmclaw connectors doctor <connectorId>
swarmclaw connectors doctor-preview <connectorId> --data '{"sampleMsg":{"text":"hello"}}'
swarmclaw connectors doctor-draft --data '{"platform":"telegram","agentId":"<agentId>","config":{"token":"***"}}'
swarmclaw connectors delete <connectorId>

plugins

swarmclaw plugins list
swarmclaw plugins install --data '{"url":"https://example.com/my-plugin.mjs","filename":"my-plugin.mjs"}'
swarmclaw plugins settings-get --query pluginId=my-plugin
swarmclaw plugins settings-set --query pluginId=my-plugin --data '{"token":"***"}'
swarmclaw plugins install-deps --data '{"filename":"my-plugin.mjs","packageManager":"npm"}'

install-deps is only needed for plugins that ship with a package.json manifest and require their own workspace dependencies.

webhooks

swarmclaw webhooks list
swarmclaw webhooks get <webhookId>
swarmclaw webhooks create --name "GitHub Push" --source github --event push --agent-id <agentId> --secret "my-secret"
swarmclaw webhooks update <webhookId> --event release
swarmclaw webhooks trigger <webhookId> --event push --payload '{"ref":"refs/heads/main"}'
swarmclaw webhooks delete <webhookId>

notifications

swarmclaw notifications list --query unreadOnly=true
swarmclaw notifications mark-read <notificationId>
swarmclaw notifications clear

Notes

• SwarmClaw keeps a route-to-command coverage test so mapped CLI commands stay aligned with API routes. Maintainers can run:

npm run test:cli

• The CLI surface evolves quickly; for the exact command and option list on your installed version, always use:

swarmclaw --help
swarmclaw <group> --help