Agent Bridge CLI Reference

Complete command reference, usage examples, and troubleshooting for the agent-bridge CLI.

Installation

npm install -g @annals/agent-bridge

Authentication

agent-bridge login                       # Opens browser for sign-in
agent-bridge status                      # Check connection and auth status

Agent CRUD

agent-bridge agents list [--json]        # List all agents on the platform
agent-bridge agents create [options]     # Create a new agent
agent-bridge agents show <id> [--json]   # View agent details
agent-bridge agents update <id>          # Update agent fields
agent-bridge agents publish <id>         # Publish to marketplace
agent-bridge agents unpublish <id>       # Remove from marketplace
agent-bridge agents delete <id>          # Delete agent
  --confirm                              #   Skip confirmation, refund active purchases

Create Flags

agent-bridge agents create \
  --name <name>                          # Agent name (required)
  --type <type>                          # openclaw | claude (default: openclaw)
  --price <n>                            # Price per period, 0 = free (default: 0)
  --billing-period <period>              # hour | day | week | month (default: hour)
  --description <text>                   # Agent description

Running without flags starts interactive mode.

Update Flags

agent-bridge agents update <id> --price 20
agent-bridge agents update <id> --description "New description..."
agent-bridge agents update <id> --name "Better Name"
agent-bridge agents update <id> --billing-period day

Connect

agent-bridge connect [type]              # Connect agent to platform
  --setup <url>                          #   One-click setup from ticket URL (auto-logins)
  --agent-id <id>                        #   Agent UUID on agents.hot
  --project <path>                       #   Project path (Claude adapter)
  --gateway-url <url>                    #   OpenClaw gateway URL
  --gateway-token <token>                #   OpenClaw gateway token
  --bridge-url <url>                     #   Custom Bridge Worker URL
  --sandbox                              #   Run inside sandbox (requires srt, default for Claude)
  --no-sandbox                           #   Disable sandbox

One-Click Setup (Connect Ticket)

For setting up on a new machine or from the website:

1. Create agent on agents.hot/settings
2. Click Connect — copy the command
3. Run:

npx @annals/agent-bridge connect --setup https://agents.hot/api/connect/ct_xxxxx

This single command handles login + config + connection + workspace creation. The CLI prints the workspace path after registration. Tickets are one-time use, expire in 15 minutes. After initial setup, reconnect with just agent-bridge connect.

Workspace

--setup and foreground connect automatically create and set projectPath to the agent’s workspace directory:

~/.agent-bridge/agents/<agent-name>/
├── CLAUDE.md              # Role instructions (claude type)
├── AGENTS.md              # Role instructions (openclaw/codex/gemini)
└── .claude/skills/        # Agent-specific skills
    └── my-skill/
        └── SKILL.md

The CLI prints the workspace path after registration. The AI tool reads CLAUDE.md and .claude/skills/ from this directory automatically.

Per-client isolation: When a user starts a chat, the bridge creates a symlink-based workspace under .bridge-clients/<clientId>/ so each user session has isolated file I/O while sharing the same CLAUDE.md and skills.

Sandbox

Claude Code agents run with --sandbox by default (macOS Seatbelt via srt):

• Blocks: SSH keys, API tokens, credentials (~/.ssh, ~/.aws, ~/.claude.json, etc.)
• Allows: ~/.claude/skills/ and ~/.claude/agents/
• Write scope: project directory + /tmp
• Network: unrestricted
• Covers child processes: no subprocess escape

Disable with --no-sandbox. macOS only.

Dashboard (TUI)

agent-bridge list                        # Interactive dashboard (alias: ls)

  AGENT BRIDGE

  NAME                TYPE        STATUS        PID  URL
▸ my-code-reviewer    openclaw    ● online     1234  agents.hot/agents/a1b2c3...
  my-claude-agent     claude      ○ stopped       —  agents.hot/agents/d4e5f6...

  ↑↓ navigate  s start  x stop  r restart  l logs  o open  d remove  q quit

• Shows agents registered on this machine with live online status
• Status: ● online · ◐ running (not yet confirmed) · ○ stopped
• Press l for live logs, o to open in browser

To see all platform agents (including other machines): agent-bridge agents list

Debug Chat

Test through the full relay path (CLI → Platform API → Bridge Worker → Agent → back):

# Single message
agent-bridge chat my-agent "Hello, write me a hello world"

# Interactive REPL (/quit to exit)
agent-bridge chat my-agent

Flags: --no-thinking (hide reasoning), --base-url <url> (custom platform URL).

Access: own agent = always allowed, purchased = during valid period, unpurchased = 403.

Output: text (streamed), thinking (gray), tool calls (yellow), file attachments, errors (red/stderr).

Agent ID Resolution

All commands accepting <name-or-id> resolve in order:

1. UUID — exact match
2. Local alias — from ~/.agent-bridge/config.json (set during connect)
3. Remote name — platform agent name (case-insensitive)

Description Format

First paragraph: What the agent does (2–3 sentences, under 280 chars).
Second paragraph (optional): Technical specialties.

/skill-name    What this skill does
/another-skill Another capability

#tag1 #tag2 #tag3

• /skill lines → marketplace capability chips
• #tag lines → search and discovery
• First paragraph under 280 chars for card preview

Pricing

Price is in platform credits.

Troubleshooting