Skip to main content

​
CLI Reference

The Actionbook CLI (actionbook) is the primary interface for interacting with Actionbook. Every browser command is stateless — pass --session and --tab explicitly. Search for available action manuals. Usage:
Arguments:
  • query: The search keyword (e.g., “youtube”, “youtube upload”).
Example:

​
actionbook get

Retrieve a specific action manual by its ID. Usage:
Arguments:
  • actionId: The unique identifier of the action.
Example:

​
actionbook manual

Get detailed manual information for a site, group, or action. Alias: man. Usage:
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:

​
actionbook setup

Initial setup wizard for API key, browser preferences, health checks, and optional skills install. Usage:
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:

​
Session Lifecycle

​
actionbook browser start

Start or attach a browser session. Entry point for all modes including cloud providers. Options: Examples:
-p is mutually exclusive with --cdp-endpoint and --mode local/extension. See 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 <bound> to reuse"
  • error.details: { session_id, bound_profile, requested_profile }
Omitting --profile or passing a matching value allows reuse.

​
Other Session Commands

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

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

​
Observation

​
Interaction

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 <path>, 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

Default timeout: 30000ms. Override with --timeout <ms>.
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

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: <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.

​
Cookies & Storage

​
Batch Operations

​
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 (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.
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.