CLI Reference

Installation & Setup#

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

# Install with pip
pip install clawbutler-cli

# Or with uv tool (recommended)
uv tool 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 agentManage agents, related config, files, models, and skills
• ap approvalList, approve, reject, batch-process approvals and manage rules
• ap kill-switchEmergency stop and recovery (`trigger` / `recover`)
• ap activityInspect activity events, summaries, and long-running tasks
• ap sessionList, inspect, watch, and analyze agent sessions
• ap chatManage chat sessions, messages, sends, and aborts

Insights Commands

• ap auditSearch, inspect, and trace audit events
• ap costView cost summaries, trends, and breakdowns by agent/model/task
• ap budgetManage budgets, resets, and enforcement
• ap cronList, create, update, delete, and inspect cron job runs
• ap configView config versions, diff, drift check, and rollback

Productivity Commands

• ap memorySearch, inspect, and edit agent memory entries
• ap toolInspect tool monitors and refresh tool state
• ap reportGenerate reports and manage report subscriptions
• ap templateBrowse, validate, preview, and deploy templates
• ap runbookManage runbooks, versions, runs, approvals, and verification
• ap analyticsInspect root-cause, reliability, and value analytics

System Commands

• ap connectorManage connectors, artifacts, sync, security checks, and diagnostics
• ap runtime-hostList paired runtime hosts, discover instances, batch-add connectors, sync attach-mode sessions, and inspect managed projections
• ap service-tokenManage org-bound service tokens for MCP and automation
• ap orgManage organizations, members, and roles
• ap notificationView and manage notification preferences
• ap health-checkRun system health checks and diagnostics
• ap infrastructureInspect infrastructure status
• ap supply-chainInspect supply chain findings and scans

Utility Commands

• ap authLogin, logout, refresh tokens, and check identity
• ap profileManage stored connection profiles
• ap exportExport migration data and portable bundles
• ap importValidate and execute migration data import
• ap routingInspect model routing suggestions and optimization actions
• ap capabilitiesShow capability profile and limits

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>