ovr upload storybook

Requires a Storybook 8.5+ static build (storybook build). Older builds are rejected before upload, with the detected version in the error. Authenticates with a project API key — a personal access token is rejected.

This command was called ovr snapshot storybook before. That name still works and behaves identically, but it prints a deprecation notice and will be removed in a future release.

ovr upload storybook \
  --dir storybook-static \
  --server-url https://ovr.example.com \
  --branch "$BRANCH" \
  --commit "$COMMIT_SHA" \
  --name "$(git log -1 --pretty=%s)" \
  --author "$(git log -1 --pretty=%an)"

Flags

Flag	Required	Default	Description
`-d, --dir <path>`	yes		Path to the Storybook static build output
`--server-url <url>`	no	`ovr.config`’s `serverUrl`	OVR server URL
`--branch <name>`	yes		Branch name
`--commit <sha>`	yes		Commit SHA
`--name <name>`	no		Build name, e.g. the commit message
`--author <author>`	no		Commit author
`--wait`	no	`false`	Wait for the build to finish processing before exiting
`--only-affected`	no	`false`	Only capture the stories a change can affect. See below
`--timeout <seconds>`	no	`600`	Maximum seconds to wait for the build result (with `--wait`)
`-c, --config <path>`	no	auto-detected	Path to `ovr.config.ts`/`.js`/`.mjs`

By default the command uploads the build, then prints the build page URL and exits 0 as soon as the build is published — it doesn’t wait for processing or review. Pass --wait to block until the build resolves or --timeout elapses instead. Exit code then reflects the outcome:

Outcome	Exit code
Unchanged, auto-approved, or already approved	`0`
Needs review	non-zero
Failed	non-zero
Timed out	non-zero

Only affected stories

Pass --only-affected to capture only the stories a change can affect. Every other story is listed on the build as skipped and keeps its baseline. Stories without a baseline for a viewport are always captured. It needs:

Storybook built with --stats-json by the Vite, Webpack 5 or Rspack (storybook-builder-rsbuild) builder, and ovr run from the directory it was built in.
The full git history. In GitHub Actions, check out with fetch-depth: 0.
A successful build on the project’s main branch in the commit’s history to compare against.

When any of these is missing, or a change could affect every story (Storybook or build configuration, dependencies, global styles), every story is captured and the CLI prints why. Use onlyAffected in ovr.config for files that affect stories without being imported.

We recommend it for pull requests only, and capturing every story on the main branch.

CI example

- name: Build Storybook
  run: pnpm build-storybook

- name: Snapshot with OVR
  env:
    OVR_API_KEY: ${{ secrets.OVR_API_KEY }}
  run: |
    npx @open-visual-regression/cli upload storybook \
      --dir storybook-static \
      --server-url https://ovr.example.com \
      --branch "${{ github.head_ref || github.ref_name }}" \
      --commit "${{ github.event.pull_request.head.sha || github.sha }}" \
      --name "$(git log -1 --pretty=%s)" \
      --author "$(git log -1 --pretty=%an)"

Every story is captured at the viewports from ovr.config, unless overridden with per-story parameters.

Get Started

CLI

Configuration

Self-Hosting

Flags

Only affected stories

CI example

​Flags

​Only affected stories

​CI example

Flags

Only affected stories

CI example