StepshotsCommands
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. |
Pass --json to any command for machine-readable output in CI pipelines and AI agent workflows. See the CI & Automation guide.
Authentication
stepshots login
Log in via your browser and store an API token locally.
stepshots login| Flag | Default | Description |
|---|---|---|
--server |
https://stepshots.com |
Server URL. Also STEPSHOTS_SERVER. |
stepshots logout
Remove the locally stored Stepshots credentials.
stepshots logoutstepshots whoami
Show which account you're logged in as.
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.
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.
stepshots schema > stepshots.schema.jsonstepshots list
List the tutorials defined in the config.
stepshots listRecording
stepshots record
Record tutorials into .stepshot bundles. Records all tutorials if none are named.
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.
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.
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.
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.
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.
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. |
--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.
Utilities
stepshots doctor
Check your setup — browser, config, server reachability, and login — in one pass. Run it first when something misbehaves.
stepshots doctor| Flag | Default | Description |
|---|---|---|
--server |
https://stepshots.com |
Server URL. Also STEPSHOTS_SERVER. |
stepshots completions
Generate shell completions.
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.
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.
stepshots serve --port 8124| Flag | Default | Description |
|---|---|---|
--port, -p |
8124 |
Port to listen on. |
--output, -o |
output/ |
Output directory for recorded bundles. |