Usage Surface

CLI Guide

The CLI is the terminal control surface for operators who want scriptable access to ClawButler. It focuses on the governance core: stored login profiles, approvals, activity, cost and budgets, config safety, connectors, runtime-host discovery and attach-mode session sync, notifications, infrastructure, templates, runbooks, and agent-config workflows that map directly to the current API contract.

Current status#

Current status
CLI now covers the daily governance path well: login/profile management, agent lifecycle control, approvals, audit and cost investigation, budgets, cron, config rollback, connector operations, runtime-host discovery and session projection, notifications, infrastructure, templates, runbooks, and migration validation. Hermes / Claude Code / Codex runtime-host support remains partial and still does not reach OpenClaw-native approval, cost, or managed-control parity.

Setup#

The current repo-supported way to run the CLI is from `apps/cli`. After dependency sync, both `ap` and `clawbutler` entry points are available through `uv run`. For day-to-day use, prefer stored login profiles over re-exporting tokens every shell session.

bash
cd apps/cli
uv sync

uv run clawbutler --version
uv run ap auth login \
  --api-url https://clawbutler.cc \
  --email [email protected]

uv run ap profile list
uv run ap capabilities

Command Reference#

Authentication

Create a stored session, refresh it, inspect the current user, or clear local tokens.

bash
uv run ap auth login --api-url https://clawbutler.cc --email [email protected]
uv run ap auth refresh
uv run ap auth whoami
uv run ap auth logout

Profiles

List stored environments, switch the active one, or remove an old profile.

bash
uv run ap profile list
uv run ap profile use staging
uv run ap profile remove old-prod

Chat

Create sessions, inspect message history, stream an assistant response in the terminal, or abort an active stream.

bash
uv run ap chat list
uv run ap chat create --agent-id <agent-id> --title "On-call triage"
uv run ap chat messages <session-id>
uv run ap chat send <session-id> "Summarize the current incident"
uv run ap chat abort <session-id>

Dashboard and activity

Read the same top-level operational picture that Web shows, then drill into recent activity and long-running work.

bash
uv run ap dashboard summary
uv run ap activity list --page 1 --page-size 20
uv run ap activity summary 2026-03-10
uv run ap activity long-tasks --status in_progress

Audit and cost

Search audit history with filters, inspect one event or trace, then review cost summary, breakdowns, trends, and freshness.

bash
uv run ap audit search --risk-level high --date-from 2026-03-01 --date-to 2026-03-10
uv run ap audit show <event-id>
uv run ap audit trace <trace-id>
uv run ap cost summary --date-from 2026-03-01 --date-to 2026-03-10
uv run ap cost trend --granularity day --group-by agent
uv run ap cost freshness

Cron, config, analytics, health

Inspect or mutate cron jobs, compare config versions, review retained analytics, inspect budgets, and verify server readiness from the terminal.

bash
uv run ap cron jobs
uv run ap cron create <agent-id> --name daily-report --expression "0 9 * * *" --command "report.generate"
uv run ap cron update <agent-id> daily-report --enabled false --description "Paused for maintenance"
uv run ap cron delete <agent-id> daily-report --confirm
uv run ap config versions <agent-id>
uv run ap config diff <agent-id> --from-version 12 --to-version 14
uv run ap analytics root-cause --days 30
uv run ap budget list
uv run ap health-check status

Connectors, runtime hosts, IM Connect, and notifications

Create or diagnose a connector, discover a local OpenClaw candidate, inspect paired runtime hosts, batch-add Hermes / Claude Code / Codex / OpenClaw instances, sync attach-mode sessions, inspect IM capabilities and channels, run QR login, and manage notification state and preferences.

bash
uv run ap connector list
uv run ap connector discovery scan-local
uv run ap connector discovery import-local --candidate-url http://127.0.0.1:8080 --name local-dev
uv run ap runtime-host list
uv run ap runtime-host discover <runtime-host-id>
uv run ap runtime-host batch-add <runtime-host-id> --instance-key <instance-key>
uv run ap runtime-host sync-sessions <runtime-host-id> --instance-key <instance-key> --max-sessions-per-instance 10 --max-messages-per-session 12
uv run ap connector diagnosis <connector-id>
uv run ap connector im capabilities <connector-id>
uv run ap connector im channels <connector-id>
uv run ap connector im config show <connector-id> slack
uv run ap connector im login start <connector-id>
uv run ap connector im login wait <connector-id>
uv run ap connector sync <connector-id>
uv run ap notification list --read false
uv run ap notification read-all
uv run ap notification preference update --email true --cooldown-minutes 15

Infrastructure and notification readiness

Inspect infrastructure status, verify readiness, and keep notification state aligned with operator workflows.

bash
uv run ap infrastructure status
uv run ap health-check status
uv run ap notification list --read false
uv run ap notification preference update --email true --cooldown-minutes 15

Memory, tool monitor, and reports

Search or edit MEMORY.md, refresh tool risk summaries, and generate or subscribe to recurring reports.

bash
uv run ap memory search --query policy
uv run ap memory latest <agent-id>
uv run ap memory edit <agent-id> --content-file ./MEMORY.md --change-reason "Refresh operating notes"
uv run ap tool summary
uv run ap tool monitors --risk-level high
uv run ap report list
uv run ap report generate --report-type weekly
uv run ap report subscription list

Templates

Create, inspect, validate, preview, deploy, or delete templates. Creation is currently file-driven so the terminal contract stays exact and scriptable.

bash
# template-body.json
{
  "name": "Ops Starter",
  "category": "operations",
  "description": "Bootstrap an operations agent",
  "template_config": {
    "model": "gpt-5",
    "temperature": 0.2
  },
  "variables": [
    { "name": "region", "type": "string", "required": true }
  ]
}

# template-vars.json
{
  "region": "us-east-1"
}

uv run ap template create --body-file ./template-body.json
uv run ap template list --category operations
uv run ap template show <template-id>
uv run ap template validate <template-id> <agent-id> --vars-file ./template-vars.json
uv run ap template preview-deploy <template-id> <agent-id> --vars-file ./template-vars.json
uv run ap template deploy <template-id> <agent-id> --vars-file ./template-vars.json --reason "Initial rollout"

Runbooks

Create or update a runbook, add an immutable version from a definition file, then trigger or inspect executions from the terminal.

bash
# runbook-body.json
{
  "name": "Budget Action Escalation",
  "description": "Escalate unusual cost spikes",
  "category": "budget_action",
  "backend": "openclaw_native",
  "trigger_type": "manual",
  "input_schema": {
    "agent_id": { "type": "string" }
  },
  "enabled": true
}

# runbook-definition.json
{
  "required_inputs": ["agent_id"],
  "steps": [
    { "id": "collect", "name": "Collect facts" },
    { "id": "summarize", "name": "Summarize action" }
  ]
}

# runbook-input.json
{
  "agent_id": "6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a"
}

uv run ap runbook create --body-file ./runbook-body.json
uv run ap runbook update <runbook-id> --body-file ./runbook-body.json
uv run ap runbook create-version <runbook-id> --definition-file ./runbook-definition.json --change-summary "Initial steps"
uv run ap runbook trigger <runbook-id> --input-file ./runbook-input.json
uv run ap runbook runs <runbook-id>
uv run ap runbook run-show <runbook-id> <run-id>

Config rollback, drift, and agent config edits

Use config safety from the terminal, inspect the same agent-config tabs that Web renders, and update workspace files, models, or skills with explicit file-driven inputs.

bash
# skills.json
[
  { "name": "search", "source": "builtin", "enabled": true }
]

uv run ap config rollback <agent-id> --target-version 12 --reason "Rollback after incident" --dry-run
uv run ap config rollback <agent-id> --target-version 12 --reason "Rollback after incident" --confirm
uv run ap config drift-check <agent-id>
uv run ap agent config overview <agent-id>
uv run ap agent config files <agent-id>
uv run ap agent config tools <agent-id>
uv run ap agent config channels <agent-id>
uv run ap agent config cron <agent-id>
uv run ap agent config raw <agent-id> --tab overview
uv run ap agent config file show <agent-id> AGENTS.md
uv run ap agent config file put <agent-id> AGENTS.md --content-file ./AGENTS.md
uv run ap agent config models update <agent-id> --primary-model gpt-5 --fallback gpt-4.1-mini
uv run ap agent config skills update <agent-id> --body-file ./skills.json

Agent management

Filter agents, create a new one, inspect it, toggle it, or delete it with confirmation.

bash
uv run ap agent list --health-status healthy --enabled true
uv run ap agent create --name EmailAgent --platform openclaw --description "Inbound email triage"
uv run ap agent show <agent-id>
uv run ap agent enable <agent-id>
uv run ap agent disable <agent-id>
uv run ap agent delete <agent-id> --confirm

Approvals

List or inspect approvals, process them one by one or in bulk, and read or update approval rules for one connector.

bash
uv run ap approval list --status all --limit 20 --page 1
uv run ap approval show <approval-id>
uv run ap approval approve <approval-id> --decision-type allow-once --reason "Reviewed by on-call"
uv run ap approval reject <approval-id> --reason "Blocked by policy"
uv run ap approval batch approve --approval-id <id-1> --approval-id <id-2> --decision-type allow-always --confirm
uv run ap approval rules show --connector-id <connector-id>
uv run ap approval rules update --connector-id <connector-id> --rules-file ./approval-rules.json

Kill switch

Review current kill state, trigger a kill switch, or recover an agent.

bash
uv run ap kill-switch status
uv run ap kill-switch trigger <agent-id> --reason "Suspicious activity"
uv run ap kill-switch recover <agent-id> --reason "Issue resolved"

Migration manifest

Create a migration export, save an import-ready manifest file, and validate it without writing data.

bash
uv run ap export manifest --group connectors --group agents --output ./migration-manifest.json
uv run ap import validate ./migration-manifest.json
uv run ap import validate ./migration-manifest.json --json

Example Workflows#

Log in once and reuse the session

Use `auth login` to create or update a stored profile. After that, normal CLI commands resolve credentials from the active profile unless explicit environment variables override them.

bash
uv run ap auth login \
  --api-url https://clawbutler.cc \
  --email [email protected]

uv run ap profile list
uv run ap auth whoami

Stream a chat reply from the terminal

CLI chat is now a real terminal workflow. Create a session, inspect the current transcript, then send a message and watch the streamed assistant response without opening the browser.

bash
uv run ap chat create --agent-id <agent-id> --title "On-call triage"
uv run ap chat messages <session-id>
uv run ap chat send <session-id> "Summarize the latest rollback chain"

Inspect agents before a maintenance window

Use `agent list` to find the target, then `agent show` to confirm health, status, and enablement before making a change.

bash
uv run ap agent list
uv run ap agent show 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --json

Process a pending approval from the terminal

List pending approvals first. Keep the default `allow-once` unless you intentionally want a durable trust rule through `allow-always`.

bash
uv run ap approval list --limit 10
uv run ap approval approve 4f65b8a2-2a17-457c-a6a7-0fbc6c16f5dc \
  --decision-type allow-once \
  --reason "Matches change request CR-1042"

Run an emergency stop

Always check current kill-switch state before recovering an agent. Recovery sends an explicit confirmation payload and a fresh idempotency key.

bash
uv run ap kill-switch status
uv run ap kill-switch trigger 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --reason "Unexpected outbound calls"
uv run ap kill-switch recover 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --reason "Traffic normalized"

Triage an incident from the terminal

Start with the dashboard, jump to filtered activity or audit records, then confirm whether cost or cron anomalies are part of the same issue.

bash
uv run ap dashboard summary
uv run ap activity list --event-type task.failed --date-from 2026-03-10
uv run ap audit search --keyword "rollback" --date-from 2026-03-10
uv run ap cost rate-alerts
uv run ap cron alerts 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a

Compare config versions before rollback planning

CLI now exposes config history, semantic diff, dry-run rollback, and manual drift detection so you can do the same investigation and recovery loop that Web exposes before applying a change.

bash
uv run ap config versions 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --page 1
uv run ap config diff 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --from-version 18 --to-version 21
uv run ap config rollback 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a --target-version 18 --reason "Preview rollback" --dry-run
uv run ap config drift-check 6d8c1f8d-4e09-4bfe-8a11-1b0f14e15a1a

Ingest a runtime host from the terminal

When the browser is unavailable, CLI can still complete the runtime-host loop: inspect paired machines, discover local runtimes, create connectors for selected instances, and project attach-mode sessions into ClawButler for investigation.

bash
uv run ap runtime-host list
uv run ap runtime-host discover <runtime-host-id>
uv run ap runtime-host batch-add <runtime-host-id> --instance-key <instance-key>
uv run ap runtime-host sync-sessions <runtime-host-id> --instance-key <instance-key>
uv run ap connector list
uv run ap notification preference show

Edit agent files, models, and skills safely

CLI now mirrors the current Web agent-config tabs for reading, and it supports the same file, model, and skills update surfaces that Web exposes today. Files auto-compute the current SHA-256 before writing, model updates are explicit flags, and skills are file-driven JSON.

bash
uv run ap agent config overview <agent-id>
uv run ap agent config tools <agent-id>
uv run ap agent config channels <agent-id>
uv run ap agent config cron <agent-id>
uv run ap agent config file show <agent-id> AGENTS.md
uv run ap agent config file put <agent-id> AGENTS.md --content-file ./AGENTS.md
uv run ap agent config models update <agent-id> --primary-model gpt-5 --fallback gpt-4.1-mini
uv run ap agent config skills update <agent-id> --body-file ./skills.json

Review memory, tool risk, and reports in one terminal pass

For operational follow-up, CLI can now move from memory search to tool risk and into report generation without changing surfaces.

bash
uv run ap memory search --query "policy"
uv run ap tool monitors --risk-level high
uv run ap report generate --report-type weekly
uv run ap report show <report-id>

Deploy a template with a preview gate

For templates, the safest terminal flow is create or inspect first, validate against a target agent, read the preview, then deploy with the exact same variable file so the browser and CLI use the same contract.

bash
uv run ap template show <template-id>
uv run ap template validate <template-id> <agent-id> --vars-file ./template-vars.json
uv run ap template preview-deploy <template-id> <agent-id> --vars-file ./template-vars.json
uv run ap template deploy <template-id> <agent-id> --vars-file ./template-vars.json --reason "Approved rollout"

Version and trigger a runbook from terminal only

Runbooks are file-driven today. Keep the definition JSON under version control, create a version from that file, then trigger the runbook with a separate input JSON or inline overrides.

bash
uv run ap runbook create-version <runbook-id> --definition-file ./runbook-definition.json --change-summary "Raise alert threshold"
uv run ap runbook trigger <runbook-id> --input-file ./runbook-input.json --input dry_run=true
uv run ap runbook runs <runbook-id>
uv run ap runbook run-show <runbook-id> <run-id>

Validate an existing migration manifest

CLI can now create a migration export and save the inline manifest as an import-ready JSON file. Validation is still read-only, so treat it as a compatibility gate rather than a write executor.

bash
uv run ap export manifest --group connectors --group agents --output ./migration-manifest.json
uv run ap import validate ./migration-manifest.json
uv run ap import validate ./migration-manifest.json --json

Parity Boundaries#

Shipped in CLI today

  • - Stored auth login (`auth login/refresh/logout/whoami`)
  • - Stored environment profiles (`profile list/use/remove`)
  • - Capability discovery (`capabilities`)
  • - Dashboard summary, activity stream, and long-task visibility
  • - Audit search / event detail / trace reconstruction
  • - Cost summary, breakdowns, trends, rate alerts, and freshness
  • - Cron jobs, runs, summary, consecutive-failure alerts, and CRUD (`cron create/update/delete`)
  • - Config version history and semantic diff
  • - Config rollback preview, execution, and drift check
  • - Streaming chat sessions and message history
  • - Memory search, latest view, history, and edit
  • - Tool monitoring summary, list, and refresh
  • - Report generation, retry, and subscription management
  • - Analytics root-cause, reliability, and value views, plus budget inspection and enforcement commands
  • - Server health and readiness checks
  • - Connector lifecycle, local discovery, and IM Connect (`connector list/show/create/update/delete/test/security-check/diagnosis/sync/discovery/im`)
  • - Runtime host lifecycle (`runtime-host list/show/discover/batch-add/sync-sessions`) for Hermes / Claude Code / Codex / OpenClaw discovery and attach-mode projection
  • - Notification inbox, subscriptions, and preference management
  • - Infrastructure status from capability profile
  • - Template lifecycle (`template list/show/create/import/validate/preview-deploy/deploy/delete`)
  • - Runbook lifecycle (`runbook list/show/create/update/versions/create-version/trigger/runs/run-show/cancel`)
  • - Web-equivalent agent config tab reads plus file/model/skills writes (`agent config overview/files/tools/channels/cron/show/raw/file/models/skills`)
  • - Agent list / create / show / enable / disable / delete
  • - Approval list / show / approve / reject / batch / rules
  • - Kill-switch status / trigger / recover
  • - Migration export with import-ready manifest output
  • - Migration import validation for existing manifests
  • - Machine-readable `--json` output on supported commands

Still missing compared with Web

  • - No current Web-only operator loop is known to be missing in CLI. Re-audit when Web ships new surfaces or mutations.
  • - Hermes / Claude Code / Codex are still runtime-host integrations: discovery, batch-add connector creation, and attach-mode session sync are shipped, while provider-native approvals, cost attribution, timelines, and managed control remain OpenClaw-first.
Where experience cannot be identical
  • - Charts, dashboards, and visual timelines can only become table/JSON/report-style terminal output, not the same visual experience.
  • - Browser permissions and mobile push flows do not map directly to a terminal. CLI can only offer equivalent alerts or handoff flows.
  • - Complex multi-pane editors in Web need a different CLI interaction model, such as opening `$EDITOR`, patch files, or guided prompts.
  • - Streaming chat in CLI is equivalent in capability, but it is still a terminal transcript rather than the browser's split-pane session UI.
  • - Runtime-host commands can discover and sync Hermes / Claude Code / Codex sessions today, but those providers still do not expose the same native control depth that OpenClaw connectors do.

Suggested Screenshots#

Screenshot Placeholder
CLI setup and capability check
Show `uv run clawbutler --version` and `uv run ap capabilities` with a valid token configured.
Screenshot Placeholder
Dashboard to audit incident flow
Show `ap dashboard summary`, `ap activity list`, and `ap audit search` in one operator workflow.
Screenshot Placeholder
Runtime host discovery and session sync workflow
Show `ap runtime-host discover`, `ap runtime-host batch-add`, and `ap runtime-host sync-sessions` in one terminal workflow.
Screenshot Placeholder
Template preview and deploy workflow
Show `ap template validate`, `ap template preview-deploy`, and `ap template deploy` using the same variables file.
Screenshot Placeholder
Runbook version and execution workflow
Show `ap runbook create-version`, `ap runbook trigger`, and `ap runbook run-show` on one runbook.
Screenshot Placeholder
Chat streaming in terminal
Show `ap chat messages` followed by `ap chat send` streaming the assistant response in place.
Screenshot Placeholder
Agent config file and model edit flow
Show `ap agent config overview`, `ap agent config channels`, `ap agent config file put`, and `ap agent config models update` on one agent.
Screenshot Placeholder
Cron CRUD and budget guardrail workflow
Show `ap cron create`, `ap cron update`, and `ap budget list` as one operator loop from scheduling to budget review.
Screenshot Placeholder
Approval decision flow in terminal
Show `ap approval list` output followed by an approval command and success confirmation.
Screenshot Placeholder
Approval batch and rules workflow
Show `ap approval batch approve` and `ap approval rules update` to handle review load and policy changes without opening Web.
CLI Guide — ClawButler