CLI reference

Commands

npx screenwalk <running-app-url> [options]
npx screenwalk <project> --url <running-app-url> [options]
npx screenwalk inspect <project> [--out <topology.json>]
npx screenwalk doctor <project> --url <running-app-url> [--json]
npx screenwalk validate <graph.json>

screenwalk

Scans a repository, captures its running UI, writes a versioned graph, starts Studio, and opens the map. When the URL is the positional argument, Screenwalk uses the current directory as the project.

doctor

Checks project path, URL connectivity, browser availability, output paths, and the optional setup recipe. Add --json for an agent or script.

inspect

Inventories runnable services, deployment configuration, documented environment URLs, integrations, and feature-flag providers without opening a browser or reading deployed secret values. Signals are labeled as configuration, dependency, or bounded source reference. They do not prove that an integration or flag is active, expose flag values, or enumerate targeting rules. Repositories with more than one browser surface require an explicit --service during capture.

validate

Validates a graph against the current versioned contract without starting capture or Studio.

Options

Option	Purpose
--url <url>	Running target application. Required for Doctor and when a project path is positional.
--service <id>	Runnable service to scan in a monorepo. Required when multiple browser surfaces are found.
--environment <name>	Explicit target identity such as local, preview, staging, or production. Otherwise Screenwalk records a URL-based inference.
--deployment-id <id>	Attach the exact deployment identifier to the completed capture when the platform exposes one.
--out <path>	Write Inspect topology JSON to a specific path. Inspect only.
--output <path>	Write the current captured graph to a specific path.
--assets-dir <path>	Write captured images to a specific directory.
--json	Print machine-readable Doctor results. Doctor only.
--viewports <list>	desktop,mobile (default), desktop, or mobile.
--setup <file>	Capture another access view with an environment-backed setup recipe.
--identity-policy <file>	Override meaningful query/hash state rules. Screenwalk automatically loads screenwalk.identity.json from the target project when present.
--max-screens <number>	Maximum screens discovered by the browser. Default: 30.
--discover-depth <n>	Safe same-origin link depth. Default: 1.
--timing-json <path>	Write route-level capture timing evidence.
--watch	Recapture affected known routes after source changes.
--no-open	Do not open the Studio browser tab.
--no-studio	Capture without starting Studio.
--help, -h	Print CLI help.

The target app must already be running. Screenwalk never replaces its dev server.

Screen identity policy

Screenwalk recognizes common state selectors such as tab, view, mode, step, panel, drawer, and modal. Tracking parameters, search/content queries, sorting/filtering, cursors, session-shaped values, and cache noise do not create screens. Unknown parameters are ignored and surfaced as a review suggestion instead of silently exploding the map.

Add screenwalk.identity.json to the target project only when its product vocabulary needs an override:

{
  "schemaVersion": "screenwalk.identity.v0",
  "query": {
    "include": ["preview", "experience"],
    "ignore": ["sort"]
  },
  "hash": {
    "include": ["pane"],
    "treatPathAsRoute": true
  }
}

Included values become meaningful variants beneath a screen family. Ignored values remain capture evidence but do not create graph nodes.

Exit failures

Failures include a stable error code and a suggested next action when one is available. Run doctor first when the browser, URL, or setup contract is unclear.