#Command line

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