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