> ## Documentation Index > Fetch the complete documentation index at: https://actionbook.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # CLI Reference > 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 theme={null} actionbook search [query] ``` **Arguments:** * `query`: The search keyword (e.g., "youtube", "youtube upload"). **Example:** ```bash theme={null} actionbook search "youtube" ``` ## `actionbook get` Retrieve a specific action manual by its ID. **Usage:** ```bash theme={null} actionbook get [actionId] ``` **Arguments:** * `actionId`: The unique identifier of the action. **Example:** ```bash theme={null} 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 theme={null} 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 theme={null} 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 theme={null} actionbook setup actionbook setup --target claude # Quick mode: install skills for an agent actionbook setup --non-interactive --api-key actionbook setup --reset ``` **Targets:** `claude`, `codex`, `cursor`, `windsurf`, `antigravity`, `opencode`, `hermes`, `standalone`, `all` *** ## `actionbook browser` Browser automation commands. After `actionbook setup`, browser command syntax is identical across all modes (local, cloud, extension). ### Global Flags These flags apply to all `actionbook browser` subcommands: | Flag | Description | | ---------------- | ------------------------------------------------- | | `--session ` | Target a specific session (defaults to `default`) | | `--tab ` | Target a specific tab | | `--json` | Output results as JSON envelope | | `--timeout ` | 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 ` | Browser mode: `local`, `extension`, or `cloud` | | `-p, --provider ` | Cloud browser provider: `driver`, `hyperbrowser`, `browseruse`. Implies `--mode cloud` | | `--session ` | Session ID (get-or-create: reuse if exists, create if not) | | `--set-session-id ` | Session ID (get-or-create: same as `--session`) | | `--open-url ` | Open this URL on start | | `--cdp-endpoint ` | Connect to an existing CDP endpoint | | `--header ` | Headers for CDP endpoint (may be repeated) | | `--headless` | Run in headless mode | | `--profile ` | Profile name | | `--stealth` / `--no-stealth` | Anti-detection mode (default: enabled) | | `--max-tracked-requests ` | Network request buffer size per tab (default: 500, range: 1–100000) | **Examples:** ```bash theme={null} 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 ``` `-p` is mutually exclusive with `--cdp-endpoint` and `--mode local/extension`. See [Cloud Providers](/guides/browser#cloud-providers) for provider-specific env vars. 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 to reuse"` * `error.details`: `{ session_id, bound_profile, requested_profile }` Omitting `--profile` or passing a matching value allows reuse. #### Other Session Commands ```bash theme={null} 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 ``` `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) ### Tab Management ```bash theme={null} 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 theme={null} actionbook browser goto --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 theme={null} # 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 "" --session s1 --tab t1 # Element text actionbook browser html --session s1 --tab t1 # Full page HTML actionbook browser html "" --session s1 --tab t1 # Element HTML actionbook browser value "" --session s1 --tab t1 # Input value # Element inspection actionbook browser attr "" href --session s1 --tab t1 # Single attribute actionbook browser attrs "" --session s1 --tab t1 # All attributes actionbook browser box "" --session s1 --tab t1 # Bounding rect actionbook browser styles "" color fontSize --session s1 --tab t1 # Computed styles actionbook browser describe "" --session s1 --tab t1 # Full element description actionbook browser state "" --session s1 --tab t1 # State flags actionbook browser inspect-point 420,310 --session s1 --tab t1 # Inspect at coordinates # Query actionbook browser query one "" --session s1 --tab t1 # Exactly one match actionbook browser query all "" --session s1 --tab t1 # All matches actionbook browser query count "" --session s1 --tab t1 # Match count actionbook browser query nth 2 "" --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 theme={null} # Click actionbook browser click "" --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 "" --count 2 --session s1 --tab t1 # Double-click # Text input actionbook browser fill "" "text" --session s1 --tab t1 # Clear field, then set value actionbook browser type "" "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 "" "value" --session s1 --tab t1 actionbook browser select "" "Display Text" --by-text --session s1 --tab t1 actionbook browser select "" @e12 --by-ref --session s1 --tab t1 # Mouse actionbook browser hover "" --session s1 --tab t1 actionbook browser focus "" --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 "" "" --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 "" /path/to/file.pdf --session s1 --tab t1 ``` `fill` clears the field and sets the value directly (like pasting). `type` simulates individual keystrokes and appends to existing content. `eval` isolates `let`/`const` scope by default. Use `--no-isolate` for multi-statement async expressions or when you need shared scope across calls. `eval` accepts the expression from three mutually-exclusive sources: a positional argument, `--file `, or stdin (`-`). Providing more than one (or none) returns `EVAL_ARGS_CONFLICT`. 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. 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). ### Wait ```bash theme={null} actionbook browser wait element "" --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 `. `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. ### Logs & Network ```bash theme={null} # 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 # 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 --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 ``` 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`. 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: earlier entries dropped (max_entries=); 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. ### Cookies & Storage ```bash theme={null} # 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 theme={null} 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 theme={null} 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. **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. *** ## `actionbook daemon` The actionbook daemon runs in the background and manages browser sessions. It auto-starts on the first CLI call. ```bash theme={null} actionbook daemon restart # Stop the running daemon (next CLI call respawns) ``` ***