Lightpanda: the headless browser designed for AI and automation
minor: standardize help options
Karl Seguina25bdc4d9bdb
diff --git a/src/help.zon b/src/help.zonindex 718561ef8..9867f737a 100644--- a/src/help.zon+++ b/src/help.zon@@ -4,12 +4,12 @@\\usage: {0s} <command> [arguments]\\\\The commands are:- \\ serve starts a WebSocket CDP server+ \\ agent starts an interactive AI agent that can browse the web\\ fetch fetches the specified URL+ \\ help displays this message\\ mcp starts an MCP (Model Context Protocol) server over stdio- \\ agent starts an interactive AI agent that can browse the web+ \\ serve starts a WebSocket CDP server\\ version displays the version of {0s}- \\ help displays this message\\\\Use "{0s} help <command>" for more information about a command.,@@ -19,12 +19,6 @@\\Starts a WebSocket CDP server.\\\\options:- \\ --host <HOST>- \\ Host of the CDP server.- \\ Defaults to "127.0.0.1".- \\ --port <INT>- \\ Port of the CDP server.- \\ Defaults to 9222.\\ --advertise-host <HOST>\\ The host to advertise, e.g. in the /json/version response. Useful,\\ for example, when --host is 0.0.0.0.@@ -32,18 +26,24 @@\\ --cdp-max-connections <INT>\\ Maximum number of simultaneous CDP connections.\\ Defaults to 16.- \\ --cdp-max-pending-connections <INT>- \\ Maximum pending connections in the accept queue.- \\ Defaults to 128.- \\ --cdp-max-message-size <INT>- \\ Maximum allowed incoming websocket message size.- \\ Defaults to 1048576 (1MB)\\ --cdp-max-http-message-size <INT>\\ Maximum allowed HTTP request size\\ Defaults to 4096 (maximum allowed: 16383)+ \\ --cdp-max-message-size <INT>+ \\ Maximum allowed incoming websocket message size.+ \\ Defaults to 1048576 (1MB)+ \\ --cdp-max-pending-connections <INT>+ \\ Maximum pending connections in the accept queue.+ \\ Defaults to 128.\\ --cookie <PATH>\\ Path to a JSON file to load cookies from (read-only).\\ Defaults to no cookie loading.+ \\ --host <HOST>+ \\ Host of the CDP server.+ \\ Defaults to "127.0.0.1".+ \\ --port <INT>+ \\ Port of the CDP server.+ \\ Defaults to 9222.,.fetch =\\usage: {0s} fetch <url>... [OPTIONS] [COMMON_OPTIONS]@@ -52,6 +52,12 @@\\than one URL requires --json.\\\\options:+ \\ --cookie <PATH>+ \\ Path to a JSON file to load cookies from (read-only).+ \\ Defaults to no cookie loading.+ \\ --cookie-jar <PATH>+ \\ Path to a JSON file to save cookies to on exit (write-only).+ \\ Defaults to no cookie saving.\\ --dump <DUMP>\\ Dumps the document to stdout.\\ Defaults to no dump.@@ -60,6 +66,18 @@\\ markdown Converts content to Markdown.\\ semantic_tree JSON-serialized semantic tree.\\ semantic_tree_text Pruned plain-text semantic tree.+ \\ --inject-script <EXPR>+ \\ JavaScript to execute as the document's <head> is parsed, before any+ \\ other scripts in the page run. Can be passed multiple times; scripts+ \\ run in order.+ \\ --inject-script-file <PATH>+ \\ Like --inject-script, but reads the script from a file. Can be passed+ \\ multiple times; can be mixed with --inject-script and runs in CLI order.+ \\ --json+ \\ Capture and print the status of the fetch as JSON. A single URL+ \\ prints one object; multiple URLs print {{"results": [ ... ]}} with+ \\ one object per URL. When used with --dump <MODE> the dumped+ \\ content is wrapped within each object.\\ --strip-mode <STRIP>\\ Comma-separated list of tag groups to remove from dump.\\ Defaults to no-strip.@@ -69,53 +87,35 @@\\ css Includes style and link[rel=stylesheet].\\ invisible Best-effort (e.g. display:none) hidden elements\\ full Strip everything.- \\ --json- \\ Capture and print the status of the fetch as JSON. A single URL- \\ prints one object; multiple URLs print {{"results": [ ... ]}} with- \\ one object per URL. When used with --dump <MODE> the dumped- \\ content is wrapped within each object.- \\ --with-base- \\ Add a <base> tag in dump.- \\ Defaults to false.- \\ --with-frames- \\ Includes the contents of iframes.- \\ Defaults to false.+ \\ --terminate-ms <INT>+ \\ Hard deadline in milliseconds. After this time elapses, JavaScript+ \\ execution is forcibly terminated (e.g. for pages with endless scripts).+ \\ Unlike --wait-ms, which only stops waiting, --terminate-ms aborts the+ \\ page.+ \\ Defaults to no terminate.\\ --wait-ms <INT>\\ Wait time in milliseconds. Supersedes all other --wait parameters.\\ Defaults to 5000.+ \\ --wait-script <EXPR>+ \\ Wait for a JavaScript expression to return truthy. Checked after+ \\ --wait-until condition is met.+ \\ --wait-script-file <PATH>+ \\ Like --wait-script, but reads the script from a file.+ \\ --wait-selector <QUERY>+ \\ Wait for an element matching the CSS selector to appear. Checked after+ \\ --wait-until condition is met.\\ --wait-until <UNTIL>\\ Wait until the specified event. Checked before other --wait-* options.\\ Defaults to 'done'. If --wait-selector, --wait-script or\\ --wait-script-file specified, defaults to none.\\ Allowed values: "load", "domcontentloaded", "networkalmostidle",\\ "networkidle", "done".- \\ --wait-selector <QUERY>- \\ Wait for an element matching the CSS selector to appear. Checked after- \\ --wait-until condition is met.- \\ --wait-script <EXPR>- \\ Wait for a JavaScript expression to return truthy. Checked after- \\ --wait-until condition is met.- \\ --wait-script-file <PATH>- \\ Like --wait-script, but reads the script from a file.- \\ --inject-script <EXPR>- \\ JavaScript to execute as the document's <head> is parsed, before any- \\ other scripts in the page run. Can be passed multiple times; scripts- \\ run in order.- \\ --inject-script-file <PATH>- \\ Like --inject-script, but reads the script from a file. Can be passed- \\ multiple times; can be mixed with --inject-script and runs in CLI order.- \\ --terminate-ms <INT>- \\ Hard deadline in milliseconds. After this time elapses, JavaScript- \\ execution is forcibly terminated (e.g. for pages with endless scripts).- \\ Unlike --wait-ms, which only stops waiting, --terminate-ms aborts the- \\ page.- \\ Defaults to no terminate.- \\ --cookie <PATH>- \\ Path to a JSON file to load cookies from (read-only).- \\ Defaults to no cookie loading.- \\ --cookie-jar <PATH>- \\ Path to a JSON file to save cookies to on exit (write-only).- \\ Defaults to no cookie saving.+ \\ --with-base+ \\ Add a <base> tag in dump.+ \\ Defaults to false.+ \\ --with-frames+ \\ Includes the contents of iframes.+ \\ Defaults to false.,.mcp =\\usage: {0s} mcp [OPTIONS] [COMMON_OPTIONS]@@ -147,107 +147,87 @@\\ {0s} agent --task "..." --save out.js (synthesize a replayable script)\\\\Arguments:- \\[SCRIPT] Optional path to a .js script. Runs the script- \\ (no LLM calls) and exits. With no script and no- \\ --task, the REPL starts; from there /load runs a- \\ script and /save exports the session to a file.- \\ Caution: .js files can contain evaluate(...) calls- \\ that run arbitrary JavaScript in the page. Only run- \\ scripts you trust, the same way you would a shell- \\ script.+ \\[SCRIPT]+ \\ Optional path to a .js script. Runs the script (no LLM calls) and+ \\ exits. With no script and no --task, the REPL starts; from there+ \\ /load runs a script and /save exports the session to a file.+ \\ Caution: .js files can contain evaluate(...) calls that run+ \\ arbitrary JavaScript in the page. Only run scripts you trust, the+ \\ same way you would a shell script.\\\\Options:- \\--provider <PROVIDER> The AI provider.- \\ When omitted, lightpanda auto-detects an API key- \\ from your environment (ANTHROPIC_API_KEY,- \\ OPENAI_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY,- \\ HF_TOKEN, AI_GATEWAY_API_KEY, MISTRAL_API_KEY).- \\ With exactly one key set: that provider is used.- \\ With multiple keys on a TTY: you'll be prompted- \\ to pick; in non-interactive contexts, pass- \\ --provider explicitly. With no keys set: falls- \\ back to the basic REPL (slash commands only, no- \\ natural-language input, no LOGIN /- \\ ACCEPT_COOKIES keywords).- \\- \\ Local servers (ollama, llama_cpp) are never- \\ auto-detected (they need no key); select them- \\ explicitly with --provider ollama / --provider- \\ llama_cpp.- \\- \\ Allowed values:- \\ "anthropic", "openai", "gemini",- \\ "huggingface", "vercel", "mistral",- \\ "ollama", "llama_cpp".- \\ In the REPL, use /provider to list and change- \\ providers.- \\- \\--no-llm Force the basic REPL even when an API key is- \\ present or --provider is set. Useful for testing- \\ slash commands without burning tokens, or for- \\ disabling the LLM in a saved command without- \\ editing the existing flags. Wins over --provider.- \\- \\--model <MODEL> The model name to use.- \\ Defaults to a sensible default per provider.- \\ In the REPL, use /model to list and change- \\ models for the active provider.- \\- \\--base-url <URL> Override the API base URL for the provider.- \\ Defaults to the provider's standard endpoint.- \\ Ollama default: http://localhost:11434/v1.- \\ llama.cpp default: http://localhost:8080/v1.- \\ Hugging Face default is the serverless router- \\ (https://router.huggingface.co/v1); point this- \\ at a dedicated Inference Endpoint to use one.- \\- \\--system-prompt <STRING> Override the default system prompt.- \\- \\--task <STRING> One-shot mode: run a single user turn, print the- \\ final answer to stdout, and exit. Conflicts with- \\ the positional script. With --save, the answer is- \\ suppressed and a script is written instead.- \\- \\--save <PATH> Synthesize a replayable .js script from the --task- \\ run and write it to PATH, instead of printing the- \\ answer. Replay it later with `agent PATH` (no LLM- \\ calls). Overwrites PATH if it exists. Requires- \\ --task.- \\- \\-a, --attach <PATH> Feed a local file to the model alongside --task.- \\ Repeatable, one file per flag. Text files are- \\ inlined (max 512 KiB each); images/audio/pdf are- \\ base64-encoded (max 20 MiB each). Requires --task.- \\- \\--list-models Print the model IDs usable with `agent` for- \\ --provider, one per line, sorted, and exit.- \\ Auto-detects the provider from env when- \\ --provider is omitted.- \\- \\--verbosity <LEVEL> Stderr chatter level.- \\ Default: high when --task captures stderr to a- \\ pipe or file; low otherwise. low/medium also- \\ raise --log-level to err (mutes page-side- \\ console.error spam) unless --log-level is set- \\ explicitly.- \\- \\ Allowed values:- \\ low Silent in --task mode (final answer to- \\ stdout only); spinner + summary in REPL.- \\ medium + one `● [tool: ...]` line per call.- \\ high + the matching `[result: ...]` body- \\ (required by the benchmarks harness).+ \\ -a, --attach <PATH>+ \\ Feed a local file to the model alongside --task. Repeatable, one+ \\ file per flag. Text files are inlined (max 512 KiB each);+ \\ images/audio/pdf are base64-encoded (max 20 MiB each).+ \\ Requires --task.+ \\ --base-url <URL>+ \\ Override the API base URL for the provider. Defaults to the+ \\ provider's standard endpoint.+ \\ Ollama default: http://localhost:11434/v1.+ \\ llama.cpp default: http://localhost:8080/v1.+ \\ Hugging Face default is the serverless router+ \\ (https://router.huggingface.co/v1);+ \\ point this at a dedicated Inference Endpoint to use one.+ \\ --effort <LEVEL>+ \\ Per-turn reasoning budget, mapped to each provider's native+ \\ thinking/reasoning knob. Default: low in the REPL (snappy turns),+ \\ medium in one-shot --task mode, unless the provider sets its own+ \\ default (Mistral defaults to none, as its default model rejects+ \\ effort). In the REPL, use /effort to change it.+ \\ Allowed values: none, minimal, low, medium, high, xhigh.+ \\ --list-models+ \\ Print the model IDs usable with `agent` for --provider, one per+ \\ line, sorted, and exit. Auto-detects the provider from env when+ \\ --provider is omitted.+ \\ --model <MODEL>+ \\ The model name to use. Defaults to a sensible default per+ \\ provider. In the REPL, use /model to list and change models for+ \\ the active provider.+ \\ --no-llm+ \\ Force the basic REPL even when an API key is present or+ \\ --provider is set. Useful for testing slash commands without+ \\ burning tokens, or for disabling the LLM in a saved command+ \\ without editing the existing flags. Wins over --provider.+ \\ --provider <PROVIDER>+ \\ The AI provider. When omitted, lightpanda auto-detects an API+ \\ key from your environment (ANTHROPIC_API_KEY, OPENAI_API_KEY,+ \\ GOOGLE_API_KEY/GEMINI_API_KEY, HF_TOKEN, AI_GATEWAY_API_KEY,+ \\ MISTRAL_API_KEY). With exactly one key set: that provider is+ \\ used. With multiple keys on a TTY: you'll be prompted to pick;+ \\ in non-interactive contexts, pass --provider explicitly. With+ \\ no keys set: falls back to the basic REPL (slash commands only,+ \\ no natural-language input, no LOGIN / ACCEPT_COOKIES keywords).\\- \\--effort <LEVEL> Per-turn reasoning budget, mapped to each- \\ provider's native thinking/reasoning knob.- \\ Default: low in the REPL (snappy turns),- \\ medium in one-shot --task mode, unless the- \\ provider sets its own default (Mistral defaults- \\ to none, as its default model rejects effort).- \\ In the REPL, use /effort to change it.+ \\ Local servers (ollama, llama_cpp) are never auto-detected (they+ \\ need no key); select them explicitly with --provider ollama /+ \\ --provider llama_cpp.\\- \\ Allowed values:- \\ none, minimal, low, medium, high, xhigh.+ \\ Allowed values: "anthropic", "openai", "gemini", "huggingface",+ \\ "vercel", "mistral", "ollama", "llama_cpp".+ \\ In the REPL, use /provider to list and change providers.+ \\ --save <PATH>+ \\ Synthesize a replayable .js script from the --task run and write+ \\ it to PATH, instead of printing the answer. Replay it later with+ \\ `agent PATH` (no LLM calls). Overwrites PATH if it exists.+ \\ Requires --task.+ \\ --system-prompt <STRING>+ \\ Override the default system prompt.+ \\ --task <STRING>+ \\ One-shot mode: run a single user turn, print the final answer+ \\ to stdout, and exit. Conflicts with the positional script. With+ \\ --save, the answer is suppressed and a script is written instead.+ \\ --verbosity <LEVEL>+ \\ Stderr chatter level. Default: high when --task captures stderr+ \\ to a pipe or file; low otherwise. low/medium also raise+ \\ --log-level to err (mutes page-side console.error spam) unless+ \\ --log-level is set explicitly.+ \\ Allowed values:+ \\ low silent in --task mode (final answer to stdout only);+ \\ spinner + summary in REPL.+ \\ medium + one `● [tool: ...]` line per call.+ \\ high + the matching `[result: ...]` body (required by the+ \\ benchmarks harness).\\\\The provider, model, effort, and verbosity you choose in the REPL are\\remembered per-directory in .lp-agent.zon and reused on the next run.@@ -269,12 +249,21 @@,.common_options =\\common options:- \\ --insecure-disable-tls-host-verification- \\ Disables host verification on all HTTP requests.- \\ Only set this if you understand and accept the risk.- \\ --obey-robots- \\ Fetches and obeys robots.txt of the target page.+ \\ --block-cidrs <LIST>+ \\ Additional CIDR ranges to block, comma-separated.+ \\ Prefix with '-' to allow (exempt from blocking).+ \\ e.g. --block-cidrs 10.0.0.0/8,-10.0.0.42/32+ \\ Can be combined with --block-private-networks.+ \\ --block-private-networks+ \\ Block HTTP requests to private/internal IP addresses after DNS+ \\ resolution.\\ Defaults to false.+ \\ --cookie <PATH>+ \\ Path to a JSON file to load cookies from (read-only).+ \\ Defaults to no cookie loading.+ \\ --cookie-jar <PATH>+ \\ Path to a JSON file to save cookies to on exit (write-only).+ \\ Defaults to no cookie saving.\\ --disable-subframes\\ Skip loading <iframe> elements. The parser still registers them in the\\ DOM, but no child frame or Page.frameAttached events are produced.@@ -289,83 +278,74 @@\\ contribute to computed styles (and therefore to visibility checks like\\ display, visibility, opacity, pointer-events).\\ Defaults to false, except in agent mode with an LLM, where it is on.- \\ --block-private-networks- \\ Block HTTP requests to private/internal IP addresses after DNS- \\ resolution.- \\ Defaults to false.- \\ --block-cidrs <LIST>- \\ Additional CIDR ranges to block, comma-separated.- \\ Prefix with '-' to allow (exempt from blocking).- \\ e.g. --block-cidrs 10.0.0.0/8,-10.0.0.42/32- \\ Can be combined with --block-private-networks.- \\ --http-proxy <URL>- \\ HTTP proxy for all HTTP requests.- \\ username:password may be included for basic auth.- \\ Defaults to none.- \\ --proxy-bearer-token <TOKEN>- \\ Token sent for bearer authentication with the proxy:- \\ Proxy-Authorization: Bearer <token>.+ \\ --http-cache-dir <PATH>+ \\ Directory used as a filesystem cache for network resources. Omitting+ \\ this disables caching.+ \\ Defaults to no caching.+ \\ --http-connect-timeout <INT>+ \\ Time in ms to establish an HTTP connection before timing out. 0 means+ \\ never.+ \\ Defaults to 0.\\ --http-max-concurrent <INT>\\ Maximum number of concurrent HTTP requests.\\ Defaults to 40.\\ --http-max-host-open <INT>\\ Maximum open connections to a given host:port.\\ Defaults to 6.- \\ --http-connect-timeout <INT>- \\ Time in ms to establish an HTTP connection before timing out. 0 means- \\ never.- \\ Defaults to 0.- \\ --http-timeout <INT>- \\ Maximum time in ms the transfer is allowed to complete. 0 means never.- \\ Defaults to 10000.\\ --http-max-response-size <INT>\\ Limits the acceptable response size for any request\\ e.g. XHR, fetch, script loading.\\ Defaults to no limit.- \\ --ws-max-concurrent <INT>- \\ Maximum number of concurrent WebSocket connections.- \\ Defaults to 8.- \\ --log-level <LEVEL>- \\ The log level.- \\ Defaults to {1s}.- \\ Allowed values: "debug", "info", "warn", "error", "fatal".- \\ --log-format <FORMAT>- \\ The log format.- \\ Defaults to {2s}.- \\ Allowed values: "pretty", "logfmt".+ \\ --http-proxy <URL>+ \\ HTTP proxy for all HTTP requests.+ \\ username:password may be included for basic auth.+ \\ Defaults to none.+ \\ --http-timeout <INT>+ \\ Maximum time in ms the transfer is allowed to complete. 0 means never.+ \\ Defaults to 10000.+ \\ --insecure-disable-tls-host-verification+ \\ Disables host verification on all HTTP requests.+ \\ Only set this if you understand and accept the risk.\\ --log-filter-scopes <SCOPES>\\ Filter logs per scope, comma-separated, applied left-to-right.\\ "-X" (or bare "X") filters out a scope, "+X" filters it in, and\\ "all" targets every scope. e.g. "http,unknown_prop" hides those\\ two; "-all,+cdp" hides everything except cdp.+ \\ --log-format <FORMAT>+ \\ The log format.+ \\ Defaults to {2s}.+ \\ Allowed values: "pretty", "logfmt".+ \\ --log-level <LEVEL>+ \\ The log level.+ \\ Defaults to {1s}.+ \\ Allowed values: "debug", "info", "warn", "error", "fatal".+ \\ --obey-robots+ \\ Fetches and obeys robots.txt of the target page.+ \\ Defaults to false.+ \\ --proxy-bearer-token <TOKEN>+ \\ Token sent for bearer authentication with the proxy:+ \\ Proxy-Authorization: Bearer <token>.+ \\ --storage-engine <ENGINE>+ \\ The storage engine to use.+ \\ Defaults to none.+ \\ Allowed values: "none", "sqlite".+ \\ --storage-sqlite-path <PATH>+ \\ Path to the SQLite database file for persistent storage.+ \\ Use ":memory:" for in-memory storage.\\ --user-agent <STRING>\\ Override the User-Agent header entirely. Must not impersonate other\\ browsers; any value containing "Mozilla" is forbidden. The browser\\ still sends Sec-Ch-Ua. Incompatible with --user-agent-suffix.\\ --user-agent-suffix <STRING>\\ Suffix appended to the Lightpanda/X.Y User-Agent.+ \\ --web-bot-auth-domain <DOMAIN>+ \\ Your domain, e.g. yourdomain.com.\\ --web-bot-auth-key-file <PATH>\\ Path to the Ed25519 private key PEM file.\\ --web-bot-auth-keyid <STRING>\\ The JWK thumbprint of your public key.- \\ --web-bot-auth-domain <DOMAIN>- \\ Your domain, e.g. yourdomain.com.- \\ --http-cache-dir <PATH>- \\ Directory used as a filesystem cache for network resources. Omitting- \\ this disables caching.- \\ Defaults to no caching.- \\ --cookie <PATH>- \\ Path to a JSON file to load cookies from (read-only).- \\ Defaults to no cookie loading.- \\ --cookie-jar <PATH>- \\ Path to a JSON file to save cookies to on exit (write-only).- \\ Defaults to no cookie saving.- \\ --storage-engine <ENGINE>- \\ The storage engine to use.- \\ Defaults to none.- \\ Allowed values: "none", "sqlite".- \\ --storage-sqlite-path <PATH>- \\ Path to the SQLite database file for persistent storage.- \\ Use ":memory:" for in-memory storage.+ \\ --ws-max-concurrent <INT>+ \\ Maximum number of concurrent WebSocket connections.+ \\ Defaults to 8.,}