Commands

The Stepshots CLI (stepshots) groups its commands into authentication, config, recording, publishing, and utilities. Run stepshots help <command> (or stepshots <command> --help) for the authoritative flag list of any command.

Global Flags

Every command accepts these flags:

Flag	Description
`--config <path>`	Path to the config file (default: auto-detect `stepshots.config.json`). Also `STEPSHOTS_CONFIG`.
`--json`	Output results as JSON to stdout — for AI agents and automation.
`--verbose`, `-v`	Enable verbose/debug logging.
`--version`, `-V`	Print the version.
`--help`, `-h`	Print help.

Tip

Pass --json to any command for machine-readable output in CI pipelines and AI agent workflows. See the CI & Automation guide.

Authentication

`stepshots login`

bash

stepshots login

Flag	Default	Description
`--server`	`https://stepshots.com`	Server URL. Also `STEPSHOTS_SERVER`.

`stepshots logout`

Remove the locally stored Stepshots credentials.

bash

stepshots logout

`stepshots whoami`

Show which account you're logged in as.

bash

stepshots whoami

Flag	Default	Description
`--server`	`https://stepshots.com`	Server URL. Also `STEPSHOTS_SERVER`.
`--token`	Stored login token	API token. Also `STEPSHOTS_TOKEN`.

Config

`stepshots init`

Generate a sample stepshots.config.json in the current directory.

bash

stepshots init

Flag	Description
`--force`	Overwrite an existing config file.

`stepshots schema`

Print the JSON Schema for stepshots.config.json — useful for validation tooling or wiring editor autocomplete.

bash

stepshots schema > stepshots.schema.json

`stepshots list`

List the tutorials defined in the config.

bash

stepshots list

Recording

`stepshots record`

Record tutorials into .stepshot bundles. Records all tutorials if none are named.

bash

stepshots record onboarding checkout

Flag	Default	Description
`[TUTORIAL]...`	All	Positional tutorial keys to record.
`--tutorial`, `-t`	All	Tutorial to record (same as the positional argument). Repeatable.
`--output`, `-o`	`output/`	Output directory for `.stepshot` files.
`--dry-run`	`false`	Validate and show what would be recorded without launching a browser.
`--profile-dir`	—	Persistent browser profile directory (for authenticated recordings). Also `STEPSHOTS_PROFILE_DIR`.

`stepshots preview`

Replay a tutorial in a visible (non-headless) browser to check your steps. Takes the tutorial key as an argument.

bash

stepshots preview onboarding

Flag	Description
`--profile-dir`	Persistent browser profile directory (for authenticated recordings). Also `STEPSHOTS_PROFILE_DIR`.

`stepshots verify`

Replay tutorials against the live app and report drift, without writing any bundle. Verifies all tutorials if none are named.

bash

stepshots verify --fail-on warn

Flag	Default	Description
`[TUTORIAL]...`	All	Positional tutorial keys to verify.
`--tutorial`, `-t`	All	Tutorial to verify (same as the positional argument). Repeatable.
`--fail-on`	`fail`	Exit non-zero on `fail` (broken steps) or `warn` (also annotation drift).
`--save-failures`	`output/`	Directory for failure screenshots.
`--profile-dir`	—	Persistent browser profile directory (for authenticated flows). Also `STEPSHOTS_PROFILE_DIR`.

`stepshots inspect`

Inspect a page to discover interactive elements and CSS selectors. Defaults to the config baseUrl if no URL is given.

bash

stepshots inspect https://example.com/pricing

Flag	Default	Description
`--width`	`1280`	Viewport width.
`--height`	`800`	Viewport height.
`--profile-dir`	—	Persistent browser profile directory (for authenticated pages). Also `STEPSHOTS_PROFILE_DIR`.

`stepshots browser`

Open a visible browser with a saved profile so you can log in to sites used by authenticated recordings. The --profile-dir flag is required; the URL is optional.

bash

stepshots browser https://example.com/login --profile-dir ~/.stepshots/profile

Flag	Description
`--profile-dir`	Persistent browser profile directory to create or reuse (required). Also `STEPSHOTS_PROFILE_DIR`.

Publishing

`stepshots upload`

Upload .stepshot bundles to the Stepshots API.

bash

stepshots upload output/onboarding.stepshot --public

Flag	Default	Description
`[FILES]...`	—	`.stepshot` files to upload.
`--title`	—	Override the demo title.
`--demo-id`	—	Replace an existing demo instead of creating a new one.
`--public`	`false`	Make new demos publicly viewable immediately (ignored with `--demo-id`).
`--server`	`https://stepshots.com`	Server URL. Also `STEPSHOTS_SERVER`.
`--token`	Stored login token	API token. Also `STEPSHOTS_TOKEN`.

Note

--token is not required. When it's omitted, upload falls back to the token stored by stepshots login. Supply --token (or STEPSHOTS_TOKEN) only for CI or headless environments where you haven't run login.

Guided tours

Work with guided-tour source files (*.tour.json) — the git-versioned asset behind Guided Tours. Paths default to the tours/ directory when omitted.

`stepshots tour init`

Scaffold a tour source file at tours/<key>.tour.json — blank, or projected once from a recorded bundle (selectors and fallback anchors carry over).

bash

stepshots tour init onboarding --from output/onboarding.stepshot

Flag	Default	Description
`<KEY>`	—	Tour key: the `?tour=` URL parameter and registry key (required).
`--from`	—	Project a recorded `.stepshot` bundle into the scaffold.
`--output`, `-o`	`tours/<key>.tour.json`	Output file.
`--force`	`false`	Overwrite an existing tour file.

`stepshots tour validate`

Statically validate tour files: strict schema parse plus lints (empty copy, duplicate keys, misplaced check hints). Exits non-zero on errors — CI-friendly.

bash

stepshots tour validate

`stepshots tour check`

Replay tour files headless against a live app and report selector drift. Each step resolves exactly like the player (selector first, then fallback anchors) and its advance action is performed: ok = selector matched, drift = only a fallback anchor matched, fail = neither.

bash

stepshots tour check --url https://staging.example.com --fail-on warn

Flag	Default	Description
`[PATH]...`	`tours/`	Tour files or directories.
`--url`	—	Base URL of the app to replay against (required).
`--fail-on`	`fail`	Exit non-zero on `fail` (broken steps) or `warn` (also fallback drift).
`--update-fallbacks`	`false`	Rewrite each selector-resolved step's fallback anchors from the live DOM.
`--profile-dir`	—	Persistent browser profile directory (for authenticated apps). Also `STEPSHOTS_PROFILE_DIR`.

`stepshots tour build`

Merge tour files into a window.__STEPSHOTS_TOURS registry script for script-tag installs. Bundler users can import the .tour.json files directly instead.

bash

stepshots tour build -o public/tours.js

`stepshots tour push`

Push tour files to Stepshots hosting: upserts by key, prints the track URL and embed snippet. One-way sync — your git files stay the source of truth; pushing overwrites the hosted copy.

bash

stepshots tour push

Flag	Default	Description
`[PATH]...`	`tours/`	Tour files or directories.
`--server`	`https://stepshots.com`	Server URL. Also `STEPSHOTS_SERVER`.
`--token`	Stored login token	API token. Also `STEPSHOTS_TOKEN`.

`stepshots tour schema`

Print the JSON Schema for *.tour.json files (the one $schema entries point at).

Note

stepshots tour export is deprecated: use tour init --from <bundle> to scaffold a source file, or tour build for the registry script.

Utilities

`stepshots doctor`

Check your setup — browser, config, server reachability, and login — in one pass. Run it first when something misbehaves.

bash

stepshots doctor

Flag	Default	Description
`--server`	`https://stepshots.com`	Server URL. Also `STEPSHOTS_SERVER`.

`stepshots completions`

Generate shell completions.

bash

stepshots completions fish > ~/.config/fish/completions/stepshots.fish

Argument	Description
`<SHELL>`	One of `bash`, `zsh`, `fish`, `powershell`, `elvish`.

`stepshots upgrade`

Upgrade stepshots in place using however you installed it.

bash

stepshots upgrade --check

Flag	Description
`--check`	Only check for updates without installing.
`--force`	Force reinstall even if already on the latest version.

`stepshots serve`

Start a local HTTP server for browser extension integration.

bash

stepshots serve --port 8124

Flag	Default	Description
`--port`, `-p`	`8124`	Port to listen on.
`--output`, `-o`	`output/`	Output directory for recorded bundles.