> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openvisualregression.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ovr upload storybook

> Upload a Storybook build and report the visual regression result.

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](/cli/authentication) — a personal access token is rejected.

<Note>
  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.
</Note>

```sh theme={null}
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](#only-affected-stories) |
| `--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`](/configuration/config#only-affected) in `ovr.config` for files that affect stories without being imported.

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

## CI example

```yaml theme={null}
- 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`](/configuration/config), unless overridden with [per-story parameters](/configuration/story-parameters).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.