uiverify CLI reference: upload and check flags

uiverify is the npm package that sends a build to UI Verify. It needs Node 24 or later, runs inside a git checkout, and reads your project key from UIVERIFY_API_KEY. For a first setup, follow the quickstart for your stack (Storybook, Playwright, Vitest, screenshots); this page is the lookup table.

The CLI has two commands over the same pipeline: bundle the directory, register the build, upload it, then wait for the verdict.

Any other command, or no command at all, prints the usage line and exits 2.

Both commands take the same input and failure-handling flags. Exactly one of --static-dir or --screenshots is required.

A value flag takes --flag value or --flag=value. An empty value counts as unset, so --api-url "$UNSET_VAR" still falls back to the environment and the default. If both --strict and --no-strict are passed, --strict wins. The removed --shadow and --build-cmd flags are accepted with a warning and ignored.

These flags control what a CI build renders and how its verdict gates the job. uiverify check rejects them.

--target picks what a preview build renders. uiverify upload rejects it.

--target is required for a Storybook --static-dir, because Storybook builds the whole suite; leaving it out is an operational failure. It is optional for a capture archive or --screenshots, which already hold only what you captured.

The CLI reads its key and build metadata from the environment. On GitHub Actions and Bitbucket Pipelines the branch, pull request and repository come from the CI's own variables, and the commit from git; the overrides win when set.

uiverify exits 0, 1 or 2. Exit 1 has two independent causes: the visual verdict, and an operational failure in strict mode.

A changed preview is the result you asked for, not a gate, so check exits 0 on it and prints the changed list for your agent to review. To make the upload verdict block merges, see Required checks.

The failed verdict means the build as a whole failed, for example because nothing could render. A story that fails to render, or fails its interaction test, inside a build that otherwise rendered turns the UI Verify pull request check red but does not change the CLI's exit code; the CLI lists it in the summary's failed count. To block merges on story failures, make the pull request check required: see Required checks.

What counts as an operational failure?

An operational failure is the run itself not happening: a missing UIVERIFY_API_KEY, a missing or empty capture directory, both --static-dir and --screenshots passed, a Storybook check without --target, or a network error, timeout or server error that survives the retries (each request is retried up to three times). The default is strict, so a dropped upload fails the job instead of leaving CI green with nothing uploaded. --no-strict logs the error and exits 0.

What counts as a malformed invocation?

A malformed invocation is a command line the CLI cannot honor: an unknown or misspelled option, a boolean given a value (--only-changed=true), a value flag with no value, a stray positional argument, an unknown command, or a flag that belongs to the other command. It exits 2 regardless of --no-strict, because --no-strict means "don't fail my job if the upload breaks", not "skip the upload", and a typo would otherwise exit 0 having uploaded nothing.

How long does upload wait for a verdict?

After uploading, the CLI polls the build every 2 seconds and prints a Rendered X / N line as the count advances. It gives up after 60 minutes, which is an operational failure. On a changed or failed verdict it prints a per-story summary and the MCP handoff for your agent. If the same commit already passed and the bundle is byte-identical, the rebuild is skipped and the CLI exits 0 straight away.

The CLI runs on any CI with Node 24+ and a git checkout. On any CI other than GitHub Actions or Bitbucket Pipelines there are no variables it knows to read, so set the branch, pull request and, if you like, the commit yourself from your CI's own variables. Many CI checkouts are a detached HEAD, where git reports the branch as HEAD, so set BRANCH explicitly.

The pull request check and comment are posted by the UI Verify GitHub App, so they need the repository on GitHub with the App connected to the project; which CI runs the upload doesn't matter. Without the App, uploads and renders still work and the CLI logs a warning. Clone with full history: in a shallow clone the CLI can't confirm which baselines are ancestors of your commit. The gh pr checks <n> --watch hint is printed only on GitHub Actions.

@uiverify/playwright replaces @playwright/test in your imports and archives every test's final page. Its uiVerify fixture has two methods.

Archives go to ./uiverify-archive, or UIVERIFY_ARCHIVE_DIR when set. A failed test is still captured; a timed-out or interrupted one is not.

@uiverify/vitest archives every browser-mode test's final DOM once uiverifyPlugin() (from @uiverify/vitest/plugin) is in your Vitest config. The in-test helpers are imported from @uiverify/vitest.

A second takeSnapshot() with the same name in one test is saved as name #2 rather than replacing the first, and takeSnapshot("", { baselineImage }) keeps the automatic snapshot's id. Each run clears the previous run's archive before writing.