Skip to main content

​
CLI Options

Complete reference of all command-line flags and options available in Agent Browser.

​
Global Options

These options can be used with any command.
OptionDescriptionDefault
—jsonOutput as JSON for machine parsingfalse
—debugEnable debug outputfalse

​
Browser Configuration

Options for configuring the browser instance.
OptionDescriptionDefault
—headedShow browser window (not headless)false
—executable-path <path>Custom browser executable pathBundled Chromium
—extension <path>Load browser extension (repeatable)None
—args <args>Browser launch args (comma or newline separated)None
—user-agent <ua>Custom User-Agent stringDefault Chrome UA
—color-scheme <scheme>Color scheme: dark, light, no-preferenceSystem default
—ignore-https-errorsIgnore HTTPS certificate errorsfalse
—allow-file-accessAllow file:// URLs to access local files (Chromium only)false

​
Session Management

Options for managing browser sessions and state.
OptionDescriptionDefault
—session <name>Use isolated sessiondefault
—session-name <name>Auto-save/restore session stateNone
—profile <path>Persistent browser profile directoryNone (ephemeral)
—state <path>Load storage state from JSON fileNone

​
Network Configuration

Options for network settings and headers.
OptionDescriptionDefault
—headers <json>Set HTTP headers scoped to the URL’s originNone
—proxy <url>Proxy server URL with optional authNone
—proxy-bypass <hosts>Hosts to bypass proxy (comma-separated)None

​
Screenshot Options

Options specific to screenshot commands.
OptionDescriptionDefault
—full, -fCapture full page (not just viewport)false
—annotateAnnotated screenshot with numbered element labelsfalse

​
Snapshot Options

Options for the snapshot command.
OptionDescriptionDefault
-i, —interactiveOnly include interactive elementsfalse
-C, —cursorInclude cursor-interactive elementsfalse
-c, —compactRemove empty structural elementsfalse
-d, —depth <n>Limit tree depth to n levelsUnlimited
-s, —selector <sel>Scope snapshot to CSS selectorFull page

​
Cloud Providers

Options for cloud browser providers.
OptionDescriptionDefault
-p, —provider <name>Cloud browser provider: browserbase, browseruse, kernel, iosNone (local)
—device <name>iOS device name (for iOS provider), e.g. “iPhone 15 Pro”None

​
CDP Connection

Options for Chrome DevTools Protocol connections.
OptionDescriptionDefault
—cdp <port|url>Connect via Chrome DevTools Protocol (port or WebSocket URL)None
—auto-connectAuto-discover and connect to running Chromefalse

​
Security Options

Options for security features.
OptionDescriptionDefault
—content-boundariesWrap page output in boundary markers for LLM safetyfalse
—max-output <chars>Truncate page output to N charactersUnlimited
—allowed-domains <list>Comma-separated allowed domain patternsNone (all allowed)
—action-policy <path>Path to action policy JSON fileNone
—confirm-actions <list>Action categories requiring confirmation (comma-separated)None
—confirm-interactiveEnable interactive confirmation promptsfalse

​
Download Configuration

Options for download behavior.
OptionDescriptionDefault
—download-path <path>Default download directorySystem temp directory

​
Configuration File

Options for loading configuration.
OptionDescriptionDefault
—config <path>Use a custom config fileAuto-discover from ~/.agent-browser/config.json and ./agent-browser.json

​
Click Options

Options for the click command.
OptionDescriptionDefault
—new-tabOpen link in a new tab instead of navigating current tabfalse

​
Scroll Options

Options for the scroll command.
OptionDescriptionDefault
-s, —selector <sel>CSS selector for a scrollable containerPage viewport

​
Wait Options

Options for the wait command.
OptionDescriptionDefault
-u, —url <pattern>Wait for URL to match patternNone
-l, —load <state>Wait for load state: load, domcontentloaded, networkidleNone
-f, —fn <expression>Wait for JavaScript expression to be truthyNone
-t, —text <text>Wait for text to appear on pageNone
-d, —downloadWait for a download to completeNone
—timeout <ms>Timeout in milliseconds (for download wait)30000

​
Eval Options

Options for the eval command.
OptionDescriptionDefault
-b, —base64Decode script from base64false
—stdinRead script from stdinfalse

​
Find Options

Options for the find command.
OptionDescriptionDefault
—name <name>Filter role by accessible nameNone
—exactRequire exact text matchfalse
Options for the cookies set command.
OptionDescriptionDefault
—url <url>Cookie URL scopeCurrent page URL
—domain <domain>Cookie domainCurrent page domain
—path <path>Cookie path/
—httpOnlyMark as HTTP-onlyfalse
—secureMark as secure (HTTPS only)false
—sameSite <value>SameSite attribute: Strict, Lax, NoneNone
—expires <timestamp>Expiration timestamp (Unix seconds)Session cookie

​
Auth Options

Options for the auth save command.
OptionDescriptionRequired
—url <url>Login page URLYes
—username <user>UsernameYes
—password <pass>PasswordYes (or —password-stdin)
—password-stdinRead password from stdinNo
—username-selector <sel>Custom username field selectorNo
—password-selector <sel>Custom password field selectorNo
—submit-selector <sel>Custom submit button selectorNo

​
State Options

Options for state clear command.
OptionDescriptionDefault
-a, —allClear all saved statesfalse

​
Profiler Options

Options for profiler start command.
OptionDescriptionDefault
—categories <list>Chrome trace categories (comma-separated)Default Chrome categories

​
Diff Options

Options for diff commands.
OptionDescriptionDefault
—baseline <file>Baseline file for comparisonPrevious snapshot in session
-o, —output <file>Save diff image to custom pathAuto-generated path
-t, —threshold <value>Color threshold for screenshot diff (0-1)0.1
—screenshotAlso perform visual screenshot diff (for url diff)false
—wait-until <state>Wait strategy before diff: load, domcontentloaded, networkidleload

​
Network Options

Options for network route command.
OptionDescriptionDefault
—abortBlock requests matching URL patternfalse
—body <json>Mock response body (JSON)None

​
Boolean Flag Values

All boolean flags accept optional true or false values to override config settings: 
# Enable (equivalent to bare --headed)
agent-browser --headed true open example.com

# Disable (overrides config file setting)
agent-browser --headed false open example.com

# Bare flag defaults to true
agent-browser --headed open example.com
This applies to: --json, --full, --headed, --debug, --ignore-https-errors, --allow-file-access, --auto-connect, --annotate, --content-boundaries, --confirm-interactive.

Build docs developers (and LLMs) love

Get started for freeTalk to us