actionbook__actionbook/docs/api-reference/cli.mdx

---
title: "CLI Reference"
description: "Detailed reference for Actionbook CLI commands"
---

# CLI Reference

The Actionbook CLI (`actionbook`) is the primary interface for interacting with Actionbook. Every browser command is **stateless** — pass `--session` and `--tab` explicitly.

## `actionbook search`

Search for available action manuals.

**Usage:**

```bash
actionbook search [query]
```

**Arguments:**

- `query`: The search keyword (e.g., "youtube", "youtube upload").

**Example:**

```bash
actionbook search "youtube"
```

## `actionbook get`

Retrieve a specific action manual by its ID.

**Usage:**

```bash
actionbook get [actionId]
```

**Arguments:**

- `actionId`: The unique identifier of the action.

**Example:**

```bash
actionbook get "site/airbnb.com/page/home/element/search-button"
```

## `actionbook manual`

Get detailed manual information for a site, group, or action. Alias: `man`.

**Usage:**

```bash
actionbook manual [site] [group] [action]
```

**Arguments:**

- `site`: Site name (e.g., "youtube", "airbnb"). If omitted, lists available sites.
- `group`: Group name within the site (e.g., "videos").
- `action`: Action name within the group (e.g., "search").

**Examples:**

```bash
actionbook manual youtube                         # Overview of a site
actionbook manual youtube videos                  # Actions in a group
actionbook manual youtube videos search           # Detailed action docs
actionbook man youtube --json                     # Alias with JSON output
```

## `actionbook setup`

Initial setup wizard for API key, browser preferences, health checks, and optional skills install.

**Usage:**

```bash
actionbook setup
actionbook setup --target claude          # Quick mode: install skills for an agent
actionbook setup --non-interactive --api-key <KEY>
actionbook setup --reset
```

**Targets:** `claude`, `codex`, `cursor`, `windsurf`, `antigravity`, `opencode`, `hermes`, `standalone`, `all`

---

## `actionbook browser`

Browser automation commands.

<Note>
  After `actionbook setup`, browser command syntax is identical across all modes (local, cloud, extension).
</Note>

### Global Flags

These flags apply to all `actionbook browser` subcommands:

| Flag | Description |
|------|-------------|
| `--session <id>` | Target a specific session (defaults to `default`) |
| `--tab <id>` | Target a specific tab |
| `--json` | Output results as JSON envelope |
| `--timeout <ms>` | Set command timeout in milliseconds |

### Session Lifecycle

#### `actionbook browser start`

Start or attach a browser session. Entry point for all modes including cloud providers.

**Options:**

| Flag | Description |
|------|-------------|
| `--mode <mode>` | Browser mode: `local`, `extension`, or `cloud` |
| `-p, --provider <name>` | Cloud browser provider: `driver`, `hyperbrowser`, `browseruse`. Implies `--mode cloud` |
| `--session <id>` | Session ID (get-or-create: reuse if exists, create if not) |
| `--set-session-id <id>` | Session ID (get-or-create: same as `--session`) |
| `--open-url <url>` | Open this URL on start |
| `--cdp-endpoint <url>` | Connect to an existing CDP endpoint |
| `--header <KEY:VALUE>` | Headers for CDP endpoint (may be repeated) |
| `--headless` | Run in headless mode |
| `--profile <name>` | Profile name |
| `--stealth` / `--no-stealth` | Anti-detection mode (default: enabled) |
| `--max-tracked-requests <N>` | Network request buffer size per tab (default: 500, range: 1–100000) |

**Examples:**

```bash
actionbook browser start --set-session-id s1
actionbook browser start --session s1 --open-url https://google.com
actionbook browser start -p hyperbrowser --session s1
actionbook browser start --mode cloud --cdp-endpoint wss://browser.example.com/ws
```

<Note>
  `-p` is mutually exclusive with `--cdp-endpoint` and `--mode local/extension`.
  See [Cloud Providers](/guides/browser#cloud-providers) for provider-specific env vars.
</Note>

<Note>
  Both `--session` and `--set-session-id` are **get-or-create**: they reuse a Running session with the given ID, or create one if not found. When reusing, if `--profile` is passed and does not match the session's bound profile, the command fails with `SESSION_PROFILE_MISMATCH`:

  - `error.code`: `"SESSION_PROFILE_MISMATCH"` (retryable: false)
  - `error.hint`: `"omit --profile or pass --profile <bound> to reuse"`
  - `error.details`: `{ session_id, bound_profile, requested_profile }`

  Omitting `--profile` or passing a matching value allows reuse.
</Note>

#### Other Session Commands

```bash
actionbook browser list-sessions                      # List all active sessions
actionbook browser status --session s1                # Show session status
actionbook browser close --session s1                 # Close a session (alias: stop)
actionbook browser restart --session s1               # Restart, preserving session_id
```

<Note>
  `browser close` is **idempotent**: closing an unknown or already-closed session returns `ok: true` with `meta.warnings` instead of a fatal error. This prevents false alarms in orchestrators that call close unconditionally during cleanup.

  - Unknown/already-closed session: `ok: true`, `data: { status: "closed", closed_tabs: 0 }`, `meta.warnings: ["session not found in daemon — already closed or daemon restarted"]`
  - Another close already in flight: `SESSION_CLOSING` fatal (unchanged)
</Note>

### Tab Management

```bash
actionbook browser list-tabs --session s1                         # List tabs
actionbook browser new-tab "https://example.com" --session s1     # Open new tab (alias: open)
actionbook browser close-tab --session s1 --tab t1                # Close a tab
```

### Navigation

```bash
actionbook browser goto <url> --session s1 --tab t1              # Navigate to URL
actionbook browser back --session s1 --tab t1                    # Go back
actionbook browser forward --session s1 --tab t1                 # Go forward
actionbook browser reload --session s1 --tab t1                  # Reload page
```

`goto` supports `--wait-until` to control when the command returns: `domcontentloaded` (default), `load`, or `none`.

### Observation

```bash
# Snapshot
actionbook browser snapshot --session s1 --tab t1                # Accessibility tree with refs
actionbook browser snapshot -i --session s1 --tab t1             # Interactive elements only
actionbook browser snapshot -i -c --session s1 --tab t1          # Interactive + compact

# Page info
actionbook browser title --session s1 --tab t1                   # Page title
actionbook browser url --session s1 --tab t1                     # Current URL
actionbook browser viewport --session s1 --tab t1                # Viewport dimensions

# Content
actionbook browser text --session s1 --tab t1                    # Full page text
actionbook browser text "<selector>" --session s1 --tab t1       # Element text
actionbook browser html --session s1 --tab t1                    # Full page HTML
actionbook browser html "<selector>" --session s1 --tab t1       # Element HTML
actionbook browser value "<selector>" --session s1 --tab t1      # Input value

# Element inspection
actionbook browser attr "<selector>" href --session s1 --tab t1        # Single attribute
actionbook browser attrs "<selector>" --session s1 --tab t1            # All attributes
actionbook browser box "<selector>" --session s1 --tab t1              # Bounding rect
actionbook browser styles "<selector>" color fontSize --session s1 --tab t1  # Computed styles
actionbook browser describe "<selector>" --session s1 --tab t1         # Full element description
actionbook browser state "<selector>" --session s1 --tab t1            # State flags
actionbook browser inspect-point 420,310 --session s1 --tab t1         # Inspect at coordinates

# Query
actionbook browser query one "<selector>" --session s1 --tab t1       # Exactly one match
actionbook browser query all "<selector>" --session s1 --tab t1       # All matches
actionbook browser query count "<selector>" --session s1 --tab t1     # Match count
actionbook browser query nth 2 "<selector>" --session s1 --tab t1     # Nth match (1-based)

# Screenshot & PDF
actionbook browser screenshot output.png --session s1 --tab t1        # Screenshot
actionbook browser screenshot output.png --full --session s1 --tab t1  # Full page
actionbook browser screenshot output.png --annotate --session s1 --tab t1  # With labels
actionbook browser pdf output.pdf --session s1 --tab t1               # Save as PDF
```

### Interaction

```bash
# Click
actionbook browser click "<selector>" --session s1 --tab t1           # Click element
actionbook browser click 420,310 --session s1 --tab t1                # Click coordinates
actionbook browser click @e5 --session s1 --tab t1                    # Click by snapshot ref
actionbook browser click "<selector>" --count 2 --session s1 --tab t1  # Double-click

# Text input
actionbook browser fill "<selector>" "text" --session s1 --tab t1     # Clear field, then set value
actionbook browser type "<selector>" "text" --session s1 --tab t1     # Type keystroke by keystroke

# Keyboard
actionbook browser press Enter --session s1 --tab t1
actionbook browser press Control+A --session s1 --tab t1

# Selection
actionbook browser select "<selector>" "value" --session s1 --tab t1
actionbook browser select "<selector>" "Display Text" --by-text --session s1 --tab t1
actionbook browser select "<selector>" @e12 --by-ref --session s1 --tab t1

# Mouse
actionbook browser hover "<selector>" --session s1 --tab t1
actionbook browser focus "<selector>" --session s1 --tab t1
actionbook browser mouse-move 420,310 --session s1 --tab t1
actionbook browser cursor-position --session s1 --tab t1
actionbook browser drag "<source>" "<target>" --session s1 --tab t1

# Scroll
actionbook browser scroll down --session s1 --tab t1
actionbook browser scroll down 500 --session s1 --tab t1
actionbook browser scroll into-view @e8 --session s1 --tab t1
actionbook browser scroll top --session s1 --tab t1

# JavaScript
actionbook browser eval "document.title" --session s1 --tab t1
actionbook browser eval "document.querySelectorAll('a').length" --session s1 --tab t1
actionbook browser eval "await fetch('/api/data').then(r => r.json())" --no-isolate --session s1 --tab t1
actionbook browser eval --file script.js --session s1 --tab t1
echo 'document.title' | actionbook browser eval - --session s1 --tab t1

# File upload
actionbook browser upload "<selector>" /path/to/file.pdf --session s1 --tab t1
```

<Tip>
  `fill` clears the field and sets the value directly (like pasting). `type` simulates individual keystrokes and appends to existing content.
</Tip>

<Tip>
  `eval` isolates `let`/`const` scope by default. Use `--no-isolate` for multi-statement async expressions or when you need shared scope across calls.
</Tip>

<Note>
  `eval` accepts the expression from three mutually-exclusive sources: a positional argument, `--file <path>`, or stdin (`-`). Providing more than one (or none) returns `EVAL_ARGS_CONFLICT`.
</Note>

<Note>
  On failure, `eval` returns a structured error envelope with `error.code` set to one of:

  **Runtime errors** (after browser execution):
  - `EVAL_RUNTIME_ERROR` — JS exception (ReferenceError, TypeError, etc.)
  - `EVAL_CROSS_ORIGIN` — cross-origin fetch or SecurityError
  - `EVAL_RESPONSE_NOT_JSON` — response Content-Type is not JSON
  - `EVAL_RESPONSE_NOT_OK` — HTTP status is not 2xx
  - `EVAL_TIMEOUT` — expression did not resolve within `--timeout`

  **CLI-layer errors** (before any browser interaction):
  - `EVAL_ARGS_CONFLICT` — multiple input sources, or no source at all
  - `EVAL_FILE_NOT_FOUND` — `--file` path unreadable (not found, permission denied, invalid data)
  - `EVAL_STDIN_TTY` — positional `-` but stdin is a terminal
  - `EVAL_STDIN_EMPTY` — stdin read produced empty or whitespace-only input

  Each error includes `error.hint` and `error.details` with diagnostic fields (`reason`, and for fetch errors: `status`, `content_type`, `body_head`). Read `error.code` to branch on the failure class instead of parsing the message string.
</Note>

<Note>
  Browser commands that interact with elements, navigate, or communicate via CDP return structured `CDP_*` error codes:

  - `CDP_NODE_NOT_FOUND` — DOM node is stale or nonexistent (retryable: no)
  - `CDP_NOT_INTERACTABLE` — element exists but can't be acted on (retryable: no)
  - `CDP_NAV_TIMEOUT` — navigation or eval timeout (retryable: **yes**)
  - `CDP_TARGET_CLOSED` — CDP target closed mid-command (retryable: **yes**)
  - `CDP_PROTOCOL_ERROR` — CDP response malformed or missing fields (retryable: no)
  - `CDP_GENERIC` — unclassified CDP error (retryable: no)

  When `error.code` is a `CDP_*` code, `error.details` includes `reason` (raw CDP message) and `cdp_code` (upstream numeric code) when available. `CDP_NAV_TIMEOUT` also includes `timeout_ms`. Each code (except `CDP_GENERIC`) includes an actionable `error.hint`.

  Some interaction paths still emit the legacy `CDP_ERROR` code — these are being migrated to the structured taxonomy (ACT-999).
</Note>

### Wait

```bash
actionbook browser wait element "<selector>" --session s1 --tab t1
actionbook browser wait navigation --session s1 --tab t1
actionbook browser wait network-idle --session s1 --tab t1
actionbook browser wait condition "document.readyState === 'complete'" --session s1 --tab t1
```

Default timeout: 30000ms. Override with `--timeout <ms>`.

<Note>
  `wait network-idle` is edge-triggered: it only tracks fetch/XHR requests started after the command begins. Pre-existing background connections (SSE, WebSocket, in-flight fetches) are ignored and do not block. This is an agent-friendly settle signal, not a guarantee of global network silence.
</Note>

### Logs & Network

```bash
# Console logs
actionbook browser logs console --session s1 --tab t1
actionbook browser logs console --level warn,error --session s1 --tab t1
actionbook browser logs errors --session s1 --tab t1
actionbook browser logs daemon --tail 100 --json

# Network
actionbook browser network requests --session s1 --tab t1
actionbook browser network requests --filter /api/ --method POST --session s1 --tab t1
actionbook browser network requests --dump --out /tmp/dump --session s1 --tab t1  # Export to requests.json
actionbook browser network request <id> --session s1 --tab t1         # Full detail + response body

# HAR recording
actionbook browser network har start --session s1 --tab t1            # Start recording
actionbook browser network har stop --session s1 --tab t1             # Stop and export HAR 1.2 file
actionbook browser network har stop --session s1 --tab t1 --out /tmp/trace.har  # Custom output path
```

Use `actionbook browser doctor --json` to inspect browser hand health without
requiring an active session. Use `actionbook browser doctor --start --json` to
start the daemon if needed and verify request/response health.

HAR recording is per-tab. Multiple tabs or sessions can record independently. `har start` accepts `--max-entries N` to set the ring-buffer cap (default: 10000). Output is HAR 1.2 JSON with request/response headers and timings (no response bodies — use `--dump` for that). If `--out` is omitted, a timestamped file is created in `~/.actionbook/har/`. Redirect chains produce one entry per hop. Error codes: `HAR_ALREADY_RECORDING`, `HAR_NOT_RECORDING`.

<Note>
  When `har stop` completes and entries were dropped due to the ring-buffer cap, the envelope signals truncation:

  - `meta.truncated == true`
  - `meta.warnings` contains `"HAR_TRUNCATED: <N> earlier entries dropped (max_entries=<cap>); raise --max-entries or stop recording sooner to keep the full trace"`
  - `data.max_entries` — the configured cap at stop time

  On a clean stop (`dropped == 0`), `meta.truncated` is `false` and `meta.warnings` is empty. `data.path`, `data.count`, and `data.dropped` are always present.
</Note>

### Cookies & Storage

```bash
# Cookies (session-level, no --tab)
actionbook browser cookies list --session s1
actionbook browser cookies get session_id --session s1
actionbook browser cookies set token abc123 --session s1
actionbook browser cookies delete token --session s1
actionbook browser cookies clear --session s1

# Local Storage
actionbook browser local-storage list --session s1 --tab t1
actionbook browser local-storage get myKey --session s1 --tab t1
actionbook browser local-storage set myKey "value" --session s1 --tab t1

# Session Storage (same syntax as local-storage)
actionbook browser session-storage list --session s1 --tab t1
```

### Batch Operations

```bash
actionbook browser batch-new-tab --urls https://a.com https://b.com --session s1
actionbook browser batch-snapshot --tabs t1 t2 t3 --session s1
actionbook browser batch-click @e5 @e6 @e7 --session s1 --tab t1
```

---

## `actionbook extension`

Manage the Chrome extension used by extension mode. The extension bridge runs inside the actionbook daemon (auto-started by browser commands).

The recommended install method is the [Chrome Web Store](https://chromewebstore.google.com/detail/actionbook/bebchpafpemheedhcdabookaifcijmfo) (current version: 0.4.0). `actionbook extension install` is a local fallback — after running it, you must manually load the unpacked extension in Chrome via `chrome://extensions` > Developer mode > Load unpacked, using the path from `actionbook extension path`.

```bash
actionbook extension status                   # Bridge status + extension connection state
actionbook extension ping                     # Measure bridge RTT
actionbook extension install                  # Fallback: install to ~/Actionbook/extension/ (requires manual Chrome load)
actionbook extension install --force          # Force reinstall
actionbook extension uninstall                # Remove extension
actionbook extension path                     # Print install path, status, and version
```

`extension status` returns the bridge state (`listening`, `not_listening`, or `failed`) and whether the extension is connected. `extension ping` connects to the bridge WebSocket at `ws://127.0.0.1:19222` and measures round-trip time.

<Note>
  **Extension 0.4.0 changes:** Tabs opened by Actionbook are automatically grouped into a Chrome tab group titled "Actionbook" (toggleable via the extension popup). In extension mode, `list-tabs` now returns only Actionbook-managed tabs (debugger-attached or in the Actionbook tab group) — other user tabs are hidden. Extension versions below 0.4.0 are rejected at handshake.
</Note>

---

## `actionbook daemon`

The actionbook daemon runs in the background and manages browser sessions. It auto-starts on the first CLI call.

```bash
actionbook daemon restart                     # Stop the running daemon (next CLI call respawns)
```

---