skills/actionbook__actionbook
1
0
Fork 0
mirror of https://github.com/actionbook/actionbook.git synced 2026-09-19 03:28:06 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
test/act-975-eval-file-stdin-red
actionbook__actionbook/docs/api-reference/cli.mdx
T
Codex efc35f7e2d [packages/cli]revert: remove --auto-connect (rollback of #545) 
The --auto-connect feature's probing logic targets Chrome's legacy
/json/version endpoint. Chrome's new native "Allow remote debugging"
toggle (chrome://inspect) uses a different protocol, so --auto-connect
cannot attach to a user's daily Chrome profile — the only way to make
it work is to launch a dedicated Chrome with --remote-debugging-port
and an isolated user-data-dir, which is equivalent to `browser start`.

Rolling back so 1.5.0 ships without a misleading feature. Will revisit
once the native-toggle protocol is supported.

- Revert source changes from 9401bbee (feat: browser start --auto-connect)
- Remove --auto-connect from CLI help text (main.rs)
- Remove --auto-connect from 1.5.0 CHANGELOG entry
- Remove --auto-connect docs: docs/guides/browser.mdx, docs/api-reference/cli.mdx
- Remove --auto-connect examples from skills SKILL.md + command-reference.md

Also incorporates earlier CHANGELOG cleanups:
- Drop "ACT-" JIRA prefixes from release notes
- Drop mention of "browser send removed" (was never in a released version)
2026-04-18 00:30:25 +08:00

367 lines
14 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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>` | Always create a new session with this ID (fails if already exists) |
| `--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>
#### 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
```
### 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
# 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>
### 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` automatically falls back from **strict** (zero in-flight requests for 500ms) to **relaxed** mode on pages with persistent background traffic. Relaxed mode requires fewer than 5 new requests in a 10s window with ≤5 pending, sustained for 3s. The response includes `mode` ("strict" or "relaxed") so callers know which condition was met.
</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
# 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
```
HAR recording is per-tab. Multiple tabs or sessions can record independently. 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`.
### 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)
```
---
Reference in New Issue View Git Blame Copy Permalink