Stepshots logoStepshots

Recording with the CLI

Record, preview, and upload screenshot demos with the Stepshots CLI for stable, scripted flows.

Prerequisites

Before you start, make sure you have:

  • Chrome or Chromium browser
  • A Stepshots account
  • A Rust toolchain — only if you install with cargo install; the prebuilt binary needs none

Installation

Install the prebuilt binary (macOS Apple Silicon, Linux x86_64/aarch64):

bash
curl -sSL https://raw.githubusercontent.com/hauju/stepshots/main/install.sh | sh

Or install with Cargo (any platform with a Rust toolchain):

bash
cargo install stepshots-cli

See Installation for other platforms and the browser prerequisite.

Initialize Your Project

Create a configuration file in your project directory:

bash
stepshots init

This generates a stepshots.config.json file where you can configure the target URL, viewport size, and other settings.

Recording a Demo

Start a recording session:

bash
stepshots record

The CLI captures screenshots at each step and bundles them into a .stepshot file.

Preview Before Recording

Before recording, preview a tutorial to check that every step works. Pass the tutorial key — preview replays that tutorial in a visible (non-headless) browser so you can watch each action and catch selector issues early:

bash
stepshots preview my-tutorial

Upload to Stepshots

Log in once — this opens your browser and stores a token locally:

bash
stepshots login

Then upload your recording, passing the bundle file:

bash
stepshots upload output/my-tutorial.stepshot

The CLI uploads the .stepshot bundle to your Stepshots account. You'll get a link to view and share your demo. Add --public to publish it immediately, or --demo-id <id> to replace an existing demo. In CI, set STEPSHOTS_TOKEN instead of running login.

Generate the config from a description (AI-assisted)

You don't have to hand-write steps. With an AI coding agent — Claude Code or Codex — and the Stepshots skill, you describe the flow in plain language and the agent inspects the page, picks stable selectors, and writes stepshots.config.json for you.

Install the skill from the repo:

bash
cp -r skills/stepshots-cli-record ~/.claude/skills/

Then describe what you want to capture, for example:

Record a demo of signing up for my app at app.example.com: land on the homepage, click Get Started, enter an email, submit, and end on the dashboard.

The agent runs stepshots inspect <url> to discover selectors and produces a config like this:

json
{
  "baseUrl": "https://app.example.com",
  "viewport": { "width": 1280, "height": 800 },
  "tutorials": {
    "signup-flow": {
      "url": "/",
      "title": "Sign up for Example App",
      "steps": [
        { "action": "click", "name": "Get started", "selector": "[data-testid='get-started-btn']",
          "highlights": [{ "callout": "Start the signup flow", "position": "bottom" }] },
        { "action": "type", "name": "Enter email", "selector": "#email", "text": "demo@example.com" },
        { "action": "click", "name": "Submit", "selector": "button[type='submit']" },
        { "action": "wait", "name": "Dashboard", "selector": ".dashboard", "delay": 1500 }
      ]
    }
  }
}

Review it, then record as usual:

bash
stepshots record -t signup-flow

You stay in control: the agent writes the config, you edit anything you want, and the CLI does the capture — no manual scripting from scratch.

Record logged-in flows

Recordings run in a fresh browser, so sites you're normally signed in to appear logged out. To record an authenticated flow, log in once inside a persistent browser profile, then point recordings at the same profile:

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

# Recordings (and preview/inspect) reuse the saved session
stepshots record --tutorial my-tutorial --profile-dir ~/.stepshots/profile

Set STEPSHOTS_PROFILE_DIR to avoid repeating the flag.

Keep demos fresh with verify

Apps drift over time — a redesign can break the selectors your demo relies on. Run stepshots verify to replay your tutorials against the live app and report which steps or annotations no longer match, without writing a new bundle:

bash
stepshots verify

It's built for CI: exit code 0 means everything is fresh, and --json emits a machine-readable report with a repair hint per failure. See the CI & Automation guide.

Tips for Great Demos

  1. Keep the flow stable — Prefer selectors and states that are unlikely to change often
  2. Keep it focused — 5-10 steps is the sweet spot for engagement
  3. Use annotations — Add highlights and callouts in the web editor after uploading
  4. Test before automating — Preview locally before relying on CI or scripts
  5. Test on mobile — Preview your demo at different viewport sizes
Navigation