StepshotsThe CLI works best for stable, predictable flows like docs, marketing pages, and controlled internal demos. For fast-changing product UI, the browser extension is usually the better starting point.
Prerequisites
Before you start, make sure you have:
- Rust installed (for building the CLI)
- Chrome or Chromium browser
- A Stepshots account
Installation
Install the CLI from the crates directory:
cargo install --path crates/cliInitialize Your Project
Create a configuration file in your project directory:
stepshots initThis 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:
stepshots recordThe CLI opens a headless Chrome instance and replays the steps from your config. Use stable selectors and explicit waits where needed.
The CLI captures screenshots at each step and bundles them into a .stepshot file.
Preview Locally
Before uploading, preview your demo:
stepshots previewThis opens a local server where you can click through the recorded steps and verify everything looks right.
Upload to Stepshots
Once you're happy with the recording, upload it:
stepshots uploadThe CLI uploads the .stepshot bundle to your Stepshots account. You'll get a link to view and share your demo.
Claude Code Skill
If you use Claude Code, you can generate stepshots.config.json files from natural language instructions. Install the skill from the repo:
cp -r skills/stepshots-cli-record ~/.claude/skills/Then describe the flow you want to capture and Claude will generate the config with steps, selectors, and annotations for you.
Tips for Great Demos
- Keep the flow stable — Prefer selectors and states that are unlikely to change often
- Keep it focused — 5-10 steps is the sweet spot for engagement
- Use annotations — Add highlights and callouts in the web editor after uploading
- Test before automating — Preview locally before relying on CI or scripts
- Test on mobile — Preview your demo at different viewport sizes