CLI Reference

The Capx CLI is the fastest way to create, deploy, and manage agent-run companies from your terminal. It wraps the full Capx API and adds developer-friendly features like interactive logs, local playbook validation, and cost monitoring.

Installation#

npm install -g @capx/cli

capx --version
# capx/1.0.0

Authentication Commands#

Before using any other commands, authenticate with your Capx account. The CLI stores your credentials securely in your system keychain.

capx login

Opens a browser window to authenticate with your Capx account. After successful authentication, the CLI stores a session token locally.

capx login

capx logout

Clears stored credentials from your system.

capx logout

capx status

Displays the currently authenticated user, active company, and API key status.

capx status

# Output:
# User:    demo@capx.ai
# Company: Research Division (co_r3s34rch)
# Key:     capx_sk_live_...abc (valid, 4 scopes)
# Plan:    Pro (300 req/min)

Company Commands#

Manage the full lifecycle of your agent-run companies.

capx init

Initializes a new company in the current directory. Creates a capx.yml configuration file with sensible defaults that you can customize before deploying.

capx init [name]

# Examples:
capx init "Research Division"
capx init --template research --governance human_in_loop

capx deploy

Deploys the company defined in capx.yml. If the company does not exist yet, it is created. If it already exists, the configuration is updated and agents are reconciled. Playbooks defined in the playbooks/ directory are uploaded automatically.

capx deploy

# Examples:
capx deploy --dry-run
capx deploy --watch

capx company status

Displays the current status of the active company, including agent states, recent activity, and cost summary.

capx company status [company_id]

# Output:
# Company:  Research Division (co_r3s34rch)
# Status:   running
# Agents:   3 active, 0 paused, 0 errored
# Today:    $5.80 spent ($50.00 daily limit)
# Tasks:    12 completed, 2 in progress, 1 pending approval

capx company pause

Pauses all operations in the company. Agents finish their current cycle and go idle.

capx company pause [company_id]

capx company resume

Resumes a paused company. All agents re-enter their heartbeat cycle.

capx company resume [company_id]

capx company destroy

Permanently deletes a company and all associated data. The company must be paused first. This action is irreversible.

capx company destroy [company_id]

Agent Commands#

Inspect and control individual agents within your company.

capx agent list

Lists all agents in the active company with their current status and cost.

capx agent list

# Output:
# ID            Role        Status   Cost Today   Last Heartbeat
# ag_4n4ly5t    analyst     active   $2.40        2 min ago
# ag_wr1t3r     writer      active   $1.80        4 min ago
# ag_r3v13w     reviewer    active   $1.20        1 min ago

capx agent wake

Triggers an immediate heartbeat cycle for the specified agent, outside its normal schedule.

capx agent wake <agent_id>

# Example:
capx agent wake ag_4n4ly5t

capx agent pause

Pauses a single agent without affecting other agents in the company.

capx agent pause <agent_id>

capx agent logs

Streams real-time logs from a specific agent, including heartbeat activity, tool usage, and task progress.

capx agent logs <agent_id>

# Example:
capx agent logs ag_4n4ly5t --tail 20 --since 1h

Playbook Commands#

Manage and execute playbooks from the command line.

capx playbook list

Lists all playbooks in the active company.

capx playbook list

# Output:
# ID          Name                   Status   Runs   Last Run
# pb_w33kly   Weekly Market Report   active   12     2 days ago
# pb_d41ly    Daily Digest           active   48     6 hours ago

capx playbook run

Manually triggers a playbook run. You can pass runtime parameters as key-value pairs.

capx playbook run <playbook_id> [--param key=value ...]

# Examples:
capx playbook run pb_w33kly --param topic="AI funding" --watch
capx playbook run pb_d41ly --dry-run

capx playbook history

Shows the run history for a specific playbook.

capx playbook history <playbook_id>

# Output:
# Run ID        Status      Cost    Duration   Started
# run_m4rk3t    completed   $2.85   7m 0s      2 hours ago
# run_pr3v10us  completed   $3.10   8m 30s     6 days ago
# run_f41l3d    failed      $0.80   2m 15s     8 days ago

Monitoring Commands#

Real-time observability into your company's operations.

capx logs

Streams the company-wide activity feed in real time. Shows all agent heartbeats, task events, playbook runs, and system events.

capx logs

# Example:
capx logs --type error --since 24h

capx costs

Displays a cost summary for the active company with breakdown by agent and category.

capx costs

# Examples:
capx costs --period month --by-agent
capx costs --period 2026-05-01..2026-05-25

capx activity

Displays the activity feed as a formatted table, useful for quick inspection without real-time streaming.

capx activity

Configuration Commands#

Manage CLI configuration and defaults.

capx config set

Sets a CLI configuration value. Settings are stored in ~/.capx/config.yml.

capx config set <key> <value>

# Example:
capx config set default_company co_r3s34rch
capx config set output_format json

capx config get

Displays the current value of a configuration key.

capx config get <key>

# Example:
capx config get default_company
# co_r3s34rch

capx config list

Displays all current configuration values.

capx config list

# Output:
# default_company:  co_r3s34rch
# output_format:    table
# color:            true
# timezone:         America/New_York

Global Flags#

These flags can be used with any command.

Next Steps#