How CLI Recording Works

The stepshots record command automates browser interaction to capture screenshots for each step in your tutorials.

How It Works

The CLI launches headless Chrome via the Chrome DevTools Protocol (CDP).
It sets the viewport to the dimensions specified in your config (default: 1280×800).
For each tutorial, it navigates to the starting URL.
For each step, it executes the action (click, type, navigate, etc.), waits for the configured delay, then captures a screenshot of the viewport. For content below the fold, set sceneScrollY on the step (see Configuration).
If a click opens a link in a new tab (target="_blank"), the recorder follows it automatically and continues the flow there.
Screenshots are bundled into a .stepshot file (a zip archive with a manifest.json and WebP images).

Basic Usage

Record all tutorials:

bash

stepshots record

Record specific tutorials by key (positional or repeatable --tutorial):

bash

stepshots record onboarding checkout
stepshots record --tutorial onboarding --tutorial checkout

Change the output directory:

bash

stepshots record --output ./recordings

Dry Run

See what would be recorded without launching Chrome:

bash

stepshots record --dry-run

Previewing

Preview a tutorial in a visible (non-headless) browser window to verify your steps work correctly:

bash

stepshots preview my-tutorial

Tip

Always preview before recording. This lets you see exactly what Chrome does at each step and catch selector issues early.

Recording Logged-In Flows

Recordings run in a fresh headless browser, so sites you're normally signed in to appear logged out. Log in once inside a persistent browser profile, then point recordings at it:

bash

# One-time: opens a visible browser — log in, then press Ctrl+C
stepshots browser https://example.com/login --profile-dir ~/.stepshots/profile

# Recordings reuse the saved session
stepshots record my-tutorial --profile-dir ~/.stepshots/profile

Set STEPSHOTS_PROFILE_DIR to avoid repeating the flag. Use a dedicated profile directory — never your regular Chrome profile. See the CLI recording guide for the full workflow.

Keeping Demos Fresh

When the recorded app's UI changes, stepshots verify replays your tutorials against the live pages without writing bundles and reports broken steps — useful locally or in CI.

Troubleshooting

Chrome not found — Make sure Google Chrome or Chromium is installed and on your PATH. The CLI looks for Chrome at its default install location for your OS.

Selector not found — The step will fail with an error message showing the selector that couldn't be found, and a debug screenshot of the failing state is saved next to the would-be bundle (<key>.failed-step-<n>.png). Use stepshots preview to debug interactively.

Timeout waiting for selector — The wait action waits up to 10 seconds for an element to appear. If your page takes longer to load, add a delay to the previous step.

Screenshots look wrong — Check your viewport dimensions. Some responsive layouts behave differently at different sizes.