Stepshots logoStepshots

Quickstart

Record, upload, and share your first Stepshots demo in about five minutes. A step-by-step quickstart covering CLI install, config, recording, and publishing.

Quickstart

This guide walks you through recording your first demo, uploading it, and sharing it. At the end you'll have a published, shareable demo: a sequence of annotated screenshots recorded from your own app, viewable at a public link and ready to embed in your docs or landing page.

Prerequisites

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

Steps

1

Install the CLI

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

Verify the installation:

bash
stepshots --version
2

Initialize a config

In your project directory, run:

bash
stepshots init

This creates a stepshots.config.json with a sample tutorial and a $schema reference so your editor autocompletes and validates it.

Each step is one action followed by a screenshot. Steps can click, type, hover, select, scroll, scroll-to, navigate, wait, or press a key — enough to script most product flows. Edit the config to point at your app:

json
{
  "$schema": "https://raw.githubusercontent.com/hauju/stepshots/main/schema/stepshots.config.schema.json",
  "baseUrl": "https://your-app.com",
  "viewport": { "width": 1280, "height": 800 },
  "format": "desktop",
  "defaultDelay": 500,
  "tutorials": {
    "onboarding": {
      "url": "/",
      "title": "Onboarding Flow",
      "steps": [
        { "action": "click", "selector": "button.get-started" },
        { "action": "type", "selector": "input[name='email']", "text": "user@example.com" },
        { "action": "click", "selector": "button[type='submit']" }
      ]
    }
  }
}
3

Record the demo

bash
stepshots record

The CLI launches headless Chrome, runs the configured flow, and saves screenshots into a .stepshot bundle in the output/ directory. This works best for stable, predictable steps.

4

Log in

bash
stepshots login

This opens your browser to authorize the CLI and stores a token locally. Run stepshots whoami to confirm which account you're logged in as.

5

Upload to Stepshots

bash
stepshots upload output/onboarding.stepshot

Add --public to publish the demo immediately instead of uploading it as a private draft:

bash
stepshots upload output/onboarding.stepshot --public
6

Edit and share

Open the Stepshots dashboard, find your demo, and use the overlay editor to add highlights, callouts, or blur regions.

When you're ready, toggle visibility to Public and copy the viewer link to share it.

Troubleshooting

A step fails with "selector not found" — the element wasn't on the page when the step ran. Run stepshots preview <tutorial> to watch the flow in a visible browser and see where it diverges. Slow-loading UI usually needs a wait step or a higher defaultDelay.

Chrome isn't found — the CLI looks for Chrome/Chromium at its default install location. If yours lives elsewhere, point at it with export CHROME_PATH=/path/to/chrome.

The flow needs a logged-in session — record against an authenticated app with a persistent browser profile. Log in once with stepshots browser https://your-app.com --profile-dir .stepshots-profile, then pass the same --profile-dir (or set STEPSHOTS_PROFILE_DIR) to record, and every recording starts from that session.

Anything else — stepshots doctor checks your browser, config, server reachability, and login in one pass and tells you what's broken.

What's Next

Navigation