CLI Reference

Last updated March 19, 2026

Starting the server

The browser server must be running before you can use any other commands.

snapwright start                              # headless (no visible window)
snapwright start --visible                    # visible browser window
snapwright start --port 9998                  # custom port (default: 9999)
snapwright start --auth .auth-state.json      # load saved auth session
snapwright start --visible --auth .auth.json  # visible + auth

The server runs in the foreground. Use a separate terminal for commands, or run it in the background with your shell (snapwright start &).

snapwright navigate https://example.com

Waits for the page to fully load (network idle) before returning.

Reading the page

snapwright text      # visible text content — good for understanding what's on screen
snapwright html      # raw HTML of the page
snapwright snapshot  # accessibility tree as JSON — useful for finding selectors
snapwright url       # current URL

Start with snapwright text or snapwright snapshot when you’re unsure what’s on the page.

Interacting

snapwright click "<selector>"              # click an element
snapwright fill "<selector>" "<value>"     # type into an input field
snapwright hover "<selector>"              # hover over an element
snapwright scroll "<selector>"             # scroll element into view
snapwright scroll                          # scroll to top of page
snapwright wait <ms>                       # pause for N milliseconds

Selectors can be CSS selectors (button.submit, input[name=email]) or Playwright text selectors (text=Sign in).

Screenshots

snapwright screenshot output/page.png              # full page
snapwright screenshot output/btn.png ".my-button"  # clip to element

Screenshots are compressed automatically. See Taking Screenshots for workflows.

Auth

snapwright auth-save   # save current cookies + localStorage to --auth file

Requires --auth <file> to be set when starting the server. See Session & Auth Persistence.

Stopping

snapwright stop

Closes the browser and shuts down the server.

Environment variables

Variable	Default	Description
`SNAPWRIGHT_PORT`	`9999`	Port the server listens on
`HEADLESS`	`true`	Set to `false` for a visible browser window

Environment variables can be used instead of CLI flags:

SNAPWRIGHT_PORT=9998 snapwright start
HEADLESS=false snapwright start