shots

Generic, open-source friendly tooling to capture high-res marketing screenshots of a SaaS app.

Key idea: you log in once manually; shots saves a Playwright storage_state.json. After that, it can run repeatedly headless, optionally guided by an LLM (vision) to navigate and/or crop.

Install

python -m venv .venv
source .venv/bin/activate

pip install -e ".[llm,yaml]"
playwright install chromium

Setup

cp shots.yaml.example shots.yaml   # edit with your app's URL and shots
cp .env.example .env                # add your OPENAI_API_KEY

Both shots.yaml and .env are gitignored.

1) One-time manual login

shots login --base-url https://your-app.example.com --out-dir shots_out

This writes shots_out/storage_state.json.

2) Run screenshots from a config

export OPENAI_API_KEY=...
shots run-config --config shots.yaml --use-llm --use-llm-crop --save-source

CLI flags

Config format (YAML)

Simple (flat shots list)

Each shot is auto-wrapped into its own group with output: png.

base_url: https://your-app.example.com
start: /app
out_dir: shots_out

defaults:
  viewport_preset: desktop
  full_page: true
  max_nav_steps: 12

shots:
  - id: dashboard-hero
    description: >
      Capture the main dashboard with KPI cards and a chart visible.
      Close any modal, cookie banner, or tour overlay.
    url: /app/dashboard

  - id: integrations
    description: >
      Show Settings -> Integrations page listing available integrations.
    viewport_preset: laptop

Groups (multi-shot PDFs, labels, folders)

Use groups instead of shots for more control. Each group produces either a single PNG or a multi-page PDF.

base_url: https://your-app.example.com
start: /app
out_dir: shots_out

defaults:
  viewport_preset: desktop
  full_page: true
  max_nav_steps: 12

groups:
  - id: hero-shots
    output: png
    shots:
      - id: dashboard-hero
        description: >
          Capture the main dashboard.
        url: /app/dashboard

  - id: onboarding-deck
    output: pdf
    folder: onboarding
    label: "{id} — {url}"
    label_date: true
    shots:
      - id: step-1-welcome
        description: Show the welcome screen.
        url: /app/onboarding
      - id: step-2-profile
        description: Show the profile setup page.
        url: /app/onboarding/profile

Config reference

Notes

• --use-llm enables multi-step navigation: the model sees a screenshot + accessibility tree each step and returns one action at a time until it says done.
• --use-llm-crop asks the model to choose a crop rectangle for marketing-friendly framing, with automatic validation and retry.
• All navigation is kept same-origin as base_url.
• A detailed log is written to <out_dir>/shots.log on every run.
• If the LLM repeats a previously failed action, it is automatically re-queried with a different approach.