Every swiftbrowse command and option, generated from --help of version 0.1.2.
The AI browser for browser automation and end-to-end testing
Usage: swiftbrowse <COMMAND>
Commands:
doctor Report the environment: OS, browser binaries, versions, desktop WebView dependencies
capabilities Start a session and print the backend's capability report
run Run a JSON script of operations and print every result plus the test report
test Run end-to-end tests: every `*.test.json` / `*.spec.json` under the given paths, in parallel sessions, with retries and list/JSON/JUnit/HTML reports
snapshot Navigate and print a compact page snapshot
screenshot Navigate and save a screenshot into the evidence directory
mcp Serve the Model Context Protocol over stdio
sdk Serve the SDK protocol (JSON lines on stdin/stdout) for the TypeScript and Python SDKs
daemon Manage the warm-browser daemon that headless sessions attach to
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
Run end-to-end tests: every `*.test.json` / `*.spec.json` under the given paths, in parallel sessions, with retries and list/JSON/JUnit/HTML reports
Usage: swiftbrowse test [OPTIONS] [PATHS]...
Arguments:
[PATHS]... Test files or directories to search for `*.test.json` and `*.spec.json`, plus `*.setup.json` files that run first (e.g. to log in and save the state). Default: the current directory
Options:
-j, --workers <WORKERS>
Tests run at the same time, each in its own isolated session (default: half the CPU cores)
--retries <RETRIES>
Retry a failing test this many times; a test that passes on retry is reported as flaky [default: 0]
-g, --grep <GREP>
Only run tests whose title (`file › test @tag`) matches this regular expression
--grep-invert <GREP_INVERT>
Skip tests whose title matches this regular expression
--repeat-each <REPEAT_EACH>
Run every test this many times (to find flaky tests) [default: 1]
--shard <SHARD>
Run one part of the suite, e.g. `2/4`, to split it across CI machines
--max-failures <MAX_FAILURES>
Stop starting tests after this many failures (`-x` is `--max-failures 1`)
-x
--forbid-only
Fail if any test is marked `only` (use on CI)
--base-url <BASE_URL>
Resolve relative `navigate` URLs against this URL (overrides a file's `base_url`)
--serve <DIR>
Serve this directory over HTTP on a free local port and use it as the base URL
--web-server <COMMAND>
Start this command (e.g. `npm run dev`) before the tests and stop it after; tests wait until `--web-server-url` accepts connections. An already running server is reused
--web-server-url <URL>
--var <NAME=VALUE>
Set a `${name}` variable, overriding the file's `vars` (repeatable)
--expect-timeout-ms <EXPECT_TIMEOUT_MS>
How long assertions and actions wait for the page (default 5000) [default: 5000]
--test-timeout-ms <TEST_TIMEOUT_MS>
Budget for one test attempt, including hooks (default 30000) [default: 30000]
--trace <TRACE>
Record a trace: a screenshot and the page as text after every step, in one self-contained trace.html per test. `retain-on-failure` keeps failed tests' only [default: off] [possible values: off, on, retain-on-failure]
--video <VIDEO>
Record a video (WebM, needs ffmpeg: `npx playwright install ffmpeg`) [default: off] [possible values: off, on, retain-on-failure]
--reporter <REPORTER>
Console output: `list` (default), `dot`, `json` (results on stdout) or `quiet` [default: list]
--output-dir <OUTPUT_DIR>
Where screenshots, page snapshots and results.json go [default: test-results]
--junit <JUNIT>
Also write a JUnit XML report here
--html <HTML>
Also write a self-contained HTML report here
--list
Print the tests that would run, without running them
--headed
Show the browser window (needs a display)
--chromium <CHROMIUM>
Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR>
Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS>
Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls
Permit file:// navigation
--timeout-ms <TIMEOUT_MS>
Default per-operation timeout
--no-approval
Do not require approval for consequential clicks (CI against test environments only)
--no-daemon
Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate
Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR>
Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help
Print help
Run a JSON script of operations and print every result plus the test report
Usage: swiftbrowse run [OPTIONS] <SCRIPT>
Arguments:
<SCRIPT> Script file, or `-` for stdin
Options:
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
Serve the Model Context Protocol over stdio
Usage: swiftbrowse mcp [OPTIONS]
Options:
--no-prewarm Do not launch the default session's browser until the first tool call
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
Serve the SDK protocol (JSON lines on stdin/stdout) for the TypeScript and Python SDKs
Usage: swiftbrowse sdk [OPTIONS]
Options:
--test-defaults Test defaults, as in `swiftbrowse test`: no approval for consequential clicks, `evaluate` allowed, uploads from the working directory
--schema Print every operation with its JSON schema and exit (for code generation)
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
Report the environment: OS, browser binaries, versions, desktop WebView dependencies
Usage: swiftbrowse doctor [OPTIONS]
Options:
--json
-h, --help Print help
Navigate and print a compact page snapshot
Usage: swiftbrowse snapshot [OPTIONS] <URL>
Arguments:
<URL>
Options:
--full
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
Navigate and save a screenshot into the evidence directory
Usage: swiftbrowse screenshot [OPTIONS] <URL>
Arguments:
<URL>
Options:
--name <NAME> File name stem (no path separators) [default: screenshot]
--full-page
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
Start a session and print the backend's capability report
Usage: swiftbrowse capabilities [OPTIONS]
Options:
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
Manage the warm-browser daemon that headless sessions attach to
Usage: swiftbrowse daemon <COMMAND>
Commands:
run Run the daemon in the foreground (clients start it automatically)
status Show whether the daemons are running and what they are doing
stop Stop every running daemon; their browsers and all contexts close
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
swiftbrowse test: 0 every test passed (flaky tests count as passed), 1 a test failed, 2 the configuration or a test file is invalid (nothing ran). swiftbrowse run: 0 when every step succeeded, otherwise 1.
# Command line
Every `swiftbrowse` command and option, generated from `--help` of version 0.1.2.
```text
The AI browser for browser automation and end-to-end testing
Usage: swiftbrowse <COMMAND>
Commands:
doctor Report the environment: OS, browser binaries, versions, desktop WebView dependencies
capabilities Start a session and print the backend's capability report
run Run a JSON script of operations and print every result plus the test report
test Run end-to-end tests: every `*.test.json` / `*.spec.json` under the given paths, in parallel sessions, with retries and list/JSON/JUnit/HTML reports
snapshot Navigate and print a compact page snapshot
screenshot Navigate and save a screenshot into the evidence directory
mcp Serve the Model Context Protocol over stdio
sdk Serve the SDK protocol (JSON lines on stdin/stdout) for the TypeScript and Python SDKs
daemon Manage the warm-browser daemon that headless sessions attach to
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
-V, --version Print version
```
## swiftbrowse test
```text
Run end-to-end tests: every `*.test.json` / `*.spec.json` under the given paths, in parallel sessions, with retries and list/JSON/JUnit/HTML reports
Usage: swiftbrowse test [OPTIONS] [PATHS]...
Arguments:
[PATHS]... Test files or directories to search for `*.test.json` and `*.spec.json`, plus `*.setup.json` files that run first (e.g. to log in and save the state). Default: the current directory
Options:
-j, --workers <WORKERS>
Tests run at the same time, each in its own isolated session (default: half the CPU cores)
--retries <RETRIES>
Retry a failing test this many times; a test that passes on retry is reported as flaky [default: 0]
-g, --grep <GREP>
Only run tests whose title (`file › test @tag`) matches this regular expression
--grep-invert <GREP_INVERT>
Skip tests whose title matches this regular expression
--repeat-each <REPEAT_EACH>
Run every test this many times (to find flaky tests) [default: 1]
--shard <SHARD>
Run one part of the suite, e.g. `2/4`, to split it across CI machines
--max-failures <MAX_FAILURES>
Stop starting tests after this many failures (`-x` is `--max-failures 1`)
-x
--forbid-only
Fail if any test is marked `only` (use on CI)
--base-url <BASE_URL>
Resolve relative `navigate` URLs against this URL (overrides a file's `base_url`)
--serve <DIR>
Serve this directory over HTTP on a free local port and use it as the base URL
--web-server <COMMAND>
Start this command (e.g. `npm run dev`) before the tests and stop it after; tests wait until `--web-server-url` accepts connections. An already running server is reused
--web-server-url <URL>
--var <NAME=VALUE>
Set a `${name}` variable, overriding the file's `vars` (repeatable)
--expect-timeout-ms <EXPECT_TIMEOUT_MS>
How long assertions and actions wait for the page (default 5000) [default: 5000]
--test-timeout-ms <TEST_TIMEOUT_MS>
Budget for one test attempt, including hooks (default 30000) [default: 30000]
--trace <TRACE>
Record a trace: a screenshot and the page as text after every step, in one self-contained trace.html per test. `retain-on-failure` keeps failed tests' only [default: off] [possible values: off, on, retain-on-failure]
--video <VIDEO>
Record a video (WebM, needs ffmpeg: `npx playwright install ffmpeg`) [default: off] [possible values: off, on, retain-on-failure]
--reporter <REPORTER>
Console output: `list` (default), `dot`, `json` (results on stdout) or `quiet` [default: list]
--output-dir <OUTPUT_DIR>
Where screenshots, page snapshots and results.json go [default: test-results]
--junit <JUNIT>
Also write a JUnit XML report here
--html <HTML>
Also write a self-contained HTML report here
--list
Print the tests that would run, without running them
--headed
Show the browser window (needs a display)
--chromium <CHROMIUM>
Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR>
Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS>
Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls
Permit file:// navigation
--timeout-ms <TIMEOUT_MS>
Default per-operation timeout
--no-approval
Do not require approval for consequential clicks (CI against test environments only)
--no-daemon
Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate
Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR>
Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help
Print help
```
## swiftbrowse run
```text
Run a JSON script of operations and print every result plus the test report
Usage: swiftbrowse run [OPTIONS] <SCRIPT>
Arguments:
<SCRIPT> Script file, or `-` for stdin
Options:
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
```
## swiftbrowse mcp
```text
Serve the Model Context Protocol over stdio
Usage: swiftbrowse mcp [OPTIONS]
Options:
--no-prewarm Do not launch the default session's browser until the first tool call
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
```
## swiftbrowse sdk
```text
Serve the SDK protocol (JSON lines on stdin/stdout) for the TypeScript and Python SDKs
Usage: swiftbrowse sdk [OPTIONS]
Options:
--test-defaults Test defaults, as in `swiftbrowse test`: no approval for consequential clicks, `evaluate` allowed, uploads from the working directory
--schema Print every operation with its JSON schema and exit (for code generation)
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
```
## swiftbrowse doctor
```text
Report the environment: OS, browser binaries, versions, desktop WebView dependencies
Usage: swiftbrowse doctor [OPTIONS]
Options:
--json
-h, --help Print help
```
## swiftbrowse snapshot
```text
Navigate and print a compact page snapshot
Usage: swiftbrowse snapshot [OPTIONS] <URL>
Arguments:
<URL>
Options:
--full
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
```
## swiftbrowse screenshot
```text
Navigate and save a screenshot into the evidence directory
Usage: swiftbrowse screenshot [OPTIONS] <URL>
Arguments:
<URL>
Options:
--name <NAME> File name stem (no path separators) [default: screenshot]
--full-page
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
```
## swiftbrowse capabilities
```text
Start a session and print the backend's capability report
Usage: swiftbrowse capabilities [OPTIONS]
Options:
--headed Show the browser window (needs a display)
--chromium <CHROMIUM> Chromium binary; defaults to $SWIFTBROWSE_CHROMIUM, then discovery (see `doctor`)
--evidence-dir <EVIDENCE_DIR> Directory for screenshots and other evidence
--allow-host <ALLOW_HOSTS> Restrict navigation to these hosts (repeatable; `*.example.com` allowed)
--block-host <BLOCK_HOSTS>
--allow-file-urls Permit file:// navigation
--timeout-ms <TIMEOUT_MS> Default per-operation timeout
--no-approval Do not require approval for consequential clicks (CI against test environments only)
--no-daemon Launch a browser for this process instead of attaching to the warm-browser daemon (also `SWIFTBROWSE_DAEMON=off`)
--allow-evaluate Allow the `evaluate` operation (page scripts). `run` and `test` always allow it
--allow-upload-dir <DIR> Let `upload_file` read files from this directory (repeatable). Uploads are off without it
-h, --help Print help
```
## swiftbrowse daemon
```text
Manage the warm-browser daemon that headless sessions attach to
Usage: swiftbrowse daemon <COMMAND>
Commands:
run Run the daemon in the foreground (clients start it automatically)
status Show whether the daemons are running and what they are doing
stop Stop every running daemon; their browsers and all contexts close
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
```
## Exit codes
`swiftbrowse test`: `0` every test passed (flaky tests count as passed), `1` a test failed, `2` the configuration or a test file is invalid (nothing ran). `swiftbrowse run`: `0` when every step succeeded, otherwise `1`.