CLI Reference

Installation & Setup#

The ClawButler CLI (command: ap) is a Python tool installed via pip or uv:

# Install with pip
pip install clawbutler-cli

# Or with uv (recommended)
uv pip install clawbutler-cli

# Or run from repo
cd apps/cli && uv run ap --help

After installation, verify with:

$ ap --version

clawbutler-cli 0.1.0

Authentication#

Before using any command, authenticate with your ClawButler instance:

Log in with email/password or API token. Creates a stored profile.

$ ap auth login

Refresh an expired access token using the stored refresh token.

$ ap auth refresh

Clear stored session tokens for one or all profiles.

$ ap auth logout

Show the current authenticated user's details.

$ ap auth whoami

The CLI supports multiple profiles for switching between instances:

Show all stored profiles

$ ap profile list

Switch active profile

$ ap profile use <name>

Delete a stored profile

$ ap profile remove <name>

Command Tree#

Current top-level commands, grouped to roughly match the Web navigation.

Operate Commands

• ap dashboardRead dashboard summaries and top-level operational health
• ap agentList, show, enable, disable, kill-switch, and configure agents
• ap approvalList, approve, reject, batch-process approvals and manage rules
• ap kill-switchEmergency stop and recovery (`trigger` / `recover`)
• ap activityView real-time agent activity feed
• ap sessionList and inspect agent sessions
• ap chatStart streaming chat with an agent

Insights Commands

• ap auditSearch and export audit trail entries
• ap costView cost summaries, trends, and breakdowns by agent/model/task
• ap budgetManage budgets, view advice, adopt/dismiss recommendations
• ap cronList, create, update, delete, and inspect cron job runs
• ap configView config versions, diff, drift check, and rollback

Productivity Commands

• ap memoryView and manage agent memory entries
• ap toolMonitor tool usage, status, and call history
• ap reportGenerate, list, export, and schedule reports
• ap templateBrowse, validate, and deploy verified templates
• ap runbookList, trigger, inspect, and manage runbook executions
• ap analyticsView usage analytics and performance metrics

System Commands

• ap connectorManage connectors, discovery import, diagnostics, sync, and IM channels
• ap runtime-hostList paired runtime hosts, discover instances, batch-add connectors, and sync attach-mode sessions
• ap orgManage organizations, members, and roles
• ap notificationView and manage notification preferences
• ap health-checkRun system health checks and diagnostics
• ap infrastructureView infrastructure status and service health
• ap supply-chainView supply chain security and dependency intel

Utility Commands

• ap authLogin, logout, refresh tokens, and check identity
• ap profileManage stored connection profiles
• ap exportExport data (agents, config, audit logs) as JSON/CSV
• ap importImport configuration from file
• ap routingView and manage A2A routing rules
• ap capabilitiesDiscover agent capabilities and protocol support

Common Options#

These flags are available on most commands:

• ---json — Output as JSON instead of formatted tables
• ---page — Page number (default: 1)
• ---page-size — Items per page (default: 20, max: 100)
• ---date-from — Start date filter (YYYY-MM-DD)
• ---date-to — End date filter (YYYY-MM-DD)
• ---profile — Use a specific stored profile
• ---confirm — Required for destructive operations (delete, logout)

Example Workflows#

Daily Monitoring

Quickly check the operator state with canonical dashboard, agent, and approval commands:

$ ap dashboard summary
ap agent list --health-status error
ap approval list --status pending

Cost Investigation

Drill into cost changes with summary, by-agent, and trend commands:

$ ap cost summary --date-from 2026-04-01
ap cost by-agent --date-from 2026-04-01
ap cost trend --granularity week --date-from 2026-04-01

Emergency Response

Inspect one agent, trigger the kill switch if needed, then inspect audit history:

$ ap agent show <agent-id>
ap kill-switch trigger <agent-id> --reason "Unexpected outbound calls"
ap audit search --agent-id <agent-id> --date-from 2026-04-15

Runtime Host intake

Complete the paired-host discovery and session-sync loop from terminal only:

$ ap runtime-host list
ap runtime-host discover <runtime-host-id>
ap runtime-host batch-add <runtime-host-id> --instance-key <instance-key>
ap runtime-host sync-sessions <runtime-host-id> --instance-key <instance-key>