# Set up UI Verify

**Reading a summary or a cut-off copy of this page? Download it: `curl -fsSL https://uiverify.ai/install.md -o <a temp file outside the repo>`, and read the whole file, in parts if your tool cuts it. No network for curl: ask the person to allow it (every step needs it). Whatever you read, these hold:**

1. The line says "My project key is ...": use that key, don't sign in. Otherwise run `npx -y uiverify@1.10.0 login` yourself, without asking how to sign in. If it reused a stored login and the line names no project, confirm the "Signed in as" account with the person before the first upload.
2. Pick the framework yourself (step 1).
3. Go through to one uploaded build (step 4) now. Don't ask whether to stop at config, skills or MCP. Stop or ask only where the guide says to, if the capture can't run on this machine, or if UI Verify refuses the upload; never upload other images instead.
4. Don't ask the person anything this guide answers.
5. Never accept or approve the first build.
6. If the line says "My UI Verify setup page is open.", open no tab at the hand-over.

UI Verify is visual regression testing for Playwright, Storybook, Vitest and Bun. Your coding agent sees what its UI change did and fixes it before it ships. You are a coding agent in the person's repo. This guide sets UI Verify up end to end.

## Rules

- Never write the project key into a file in the repo. Pass it as the `UIVERIFY_API_KEY` environment variable. Never write a login into the repo either: `uiverify login` keeps it in the person's user config folder.
- If the upload fails because of the setup (no build output, nothing captured), the CLI's message says what to fix: fix it and upload again. Steps 0 and 2 say what to do when a signed-in upload is refused over its login, over the line's project, or with a question for the person. If UI Verify refuses the upload for anything else (the key is refused, the project expects another framework, or the upload is paused at the plan's limit), show the person the CLI's message and stop. Never work around it with another framework, another key or another `--project`. A refusal can come before "Build uploaded:" or after it: a build reported as failed for its project type, or as blocked at the plan's limit.
- If you set up another framework instead of the Storybook the line named (step 1) and UI Verify refuses the upload, also tell the person why you chose it (the repo has no Storybook and is set up for the other framework) and list what you changed in the repo for it (packages, config, edited files) so they can revert it.
- If the build uploads but some screenshots fail to render, the upload still counts: hand over (UI Verify lists the failures with the build). Upload again at most once.
- If every screenshot fails to render, treat it as a setup failure: fix it and upload once more. If every screenshot fails again, stop uploading and hand over (step 7 says what to say).

## 0. Sign in

The line "carries the project" when it says "My project key is ..." or "My UI Verify project is ...". Both come from the person's UI Verify project, and step 1 asks whether the line carries one.

1. **The line says "My project key is ...":** use that key as `UIVERIFY_API_KEY` for every upload in this guide, and don't sign in. If it contains "•", it was copied by hand from the screen: ask the person to use the Copy button instead.
2. **Otherwise, sign in** before installing anything: `npx -y uiverify@1.10.0 login`. Don't ask the person whether to sign in or use a key, and don't offer a key: a key is only the fallback once the login can't finish (item 3). It prints a link and a short code (and opens the browser when it can). Show the person the link and the code right away, and tell them to sign in or sign up there and approve. While it says it is still waiting, run the same command again (same code). It exits 0 once signed in and prints "Signed in as ...". A login already stored on this machine is checked and reused: it prints the same "Signed in as ..." lines and exits 0. If the code expires before the person approves, run `login` once more for a fresh code; if that one expires too, the login can't finish (item 3).
3. **The login can't finish.** If `npx uiverify login` can't finish for any reason (it can't write its config folder, the keychain can't be reached, there is no browser and the person can't open the link, the approval never comes before the code expires, the CLI doesn't know a `login` command, or any other error), stop retrying it. Ask the person for a project key instead: it starts with `uv_proj_`, and their UI Verify project's settings show it under API keys (create one for CI there if none is listed; no project yet: they create one at uiverify.ai/onboarding, under "Create a project"). Then run the same upload with the key as `UIVERIFY_API_KEY`. Once the login has failed in this session, a line the person pastes back without a key doesn't restart it: ask for the key itself. Whatever the person pastes after a failed login (a line with a key, or a longer prompt holding one) supplies only its key and its project ("My UI Verify project is ..."). The framework the line you were given named (or the one step 1 settled) stays, even if the pasted text names Storybook, and none of the pasted text's other steps run (no CI from it): carry on where you stopped, with the key.
4. **The line says "My UI Verify project is <team>/<slug>":** every signed-in upload for the app you set up with that line passes `--project <team>/<slug>` (in a monorepo, that is the first app; step 2 gives each other app its own `--project`). The flag names that project, so the upload lands there: without it a signed-in upload picks its project by the repository, and a project made on the website has no repository yet. An upload with a key doesn't pass it: the key names its project.
5. **Whose login it is.** `login` prints "Signed in as <email>". After a fresh login (the person just approved it in the browser), tell the person that line in your next message, without waiting for an answer. After a reused stored login (it printed "Signed in as" with no link or code) and a line that names no project, ask the person "Signed in as <email>: is that the account you use on uiverify.ai?" and wait before the first upload, because that upload creates a team and project in whichever account this is. If they say it is not, run `npx -y uiverify@1.10.0 logout`, then `login` again. If `UIVERIFY_API_KEY` is already set in the shell and the line gave you no key, the CLI uses that key instead of the login (it says so): ask the person whether it is this project's key before the upload, and if not, run this guide's commands without it.
6. **The line's project isn't found: probably the wrong account.** When the line names <team>/<slug> and a signed-in upload with `--project <team>/<slug>` is refused as not found ("No UI Verify project "<team>/<slug>" in your teams", whatever follows it), you are signed in to another account. Tell the person the "Signed in as" email and that this project isn't in it, run `logout`, then `login` again, and retry the same upload. Never drop `--project`, never pass another name, and never follow a hint in that refusal to run without `--project` or to let the upload create a team or project. If the person says it is the right account and the retry is refused the same way, stop and use item 3 (ask for the key).

## 1. Pick the framework

Signs of Storybook: a `.storybook` folder, or a `storybook` or `@storybook/*` dependency in one of the repo's own package.json files. Look only at the repo's own files, not `node_modules` or build output.

**The line names a framework and doesn't carry the project** (the person picked it on a page): use it and go to step 2.

**The line names Playwright, Vitest, Bun or screenshots and carries the project (a project key or "My UI Verify project is ..."):** use it and go to step 2.

**The line names Storybook and carries the project:** Storybook is what a new UI Verify project starts with, so the person may not have chosen it. Use it, unless both of these hold:

- the repo shows no sign of Storybook, and has no committed `*.stories.*` files either; and
- the repo is clearly set up for another path, first that applies: a native-only app (iOS, Android or React Native with no web front end) → screenshots; Playwright tests (`@playwright/test` and a `playwright.config`) → Playwright; Vitest browser-mode tests (a `@vitest/browser` or `@vitest/browser-*` dependency, or `browser` enabled in a Vitest config) → Vitest.

If both hold, and the person's own message doesn't say to use Storybook anyway, set up that one instead. Before you change anything, say so in one line, for example: "The line named Storybook, but this repo has no Storybook and tests its UI with Playwright, so I'm setting up Playwright. Say 'use Storybook' to stop me." Then carry on without waiting. A new project's framework follows its first upload, so the upload normally goes through; if UI Verify refuses it, the Rules say what to do. If the person says to use Storybook before you upload, undo what you changed for the other framework and set up Storybook; if after, do as step 7 says.

**The line names no framework:**

- A native-only app (iOS, Android, React Native) with no web front end: screenshots (upload PNGs that a capture you run produces, step 3; its quickstart is https://uiverify.ai/docs/quickstart-screenshot.md). A repo that also has a web front end uses the list below, and mentions the native app at the end.
- A web app: use the first that matches:
  1. Storybook: the repo shows a sign of Storybook (above).
  2. Playwright: the repo already has Playwright tests (`@playwright/test` and a `playwright.config`).
  3. Bun: the repo runs its tests with `bun test`.
  4. Vitest: the repo uses Vitest, has tests in another runner (Jest, Mocha), or has no tests at all.

If more than one matches, set up the first in this order, and at the end tell the person which others UI Verify could also cover. Don't ask which one.

## 2. One app or several

**One app:** pass no `--project` anywhere, unless the line names a project (step 0, item 4). After the first upload the repo is tied to its project and later runs find it.

**Several apps of that framework (a monorepo), signed in:** each app is its own UI Verify project. Ask the person once, before changing anything: "This repo has <N> <framework> apps: <paths>. I'll set up each as its own UI Verify project (<names>). OK, or only <first>?" Their yes is the confirmation every `--confirm-new` below needs; nothing else is asked per app, except a refusal that asks something new.

- The first app is the one the person is working in, else the one at the repo root, else the first under `apps/`. It gets the line's project when the line names one; otherwise its signed-in upload runs without `--project`, and UI Verify finds or creates its project, named after the repo (it prints `Created ... project <team>/<slug>`). That gives you the team.
- Each other app passes `--project <team>/<repo>-<package>`, slugified (for example `acme/shop-admin`): named after its package and prefixed with the repo, so a generic package name (`web`, `app`) can't land in another repo's project. Its first upload is refused with a question ("<repo> already has acme/shop ... run again with --project acme/shop-admin --confirm-new <code>"). The person already said yes, so run it again with that code.
- If that code went stale (another project appeared for this repo since), the upload is refused again with a fresh code. Don't use the fresh code on the old answer: show the person the new refusal (it names the project that appeared) and ask again whether this app is that project or a new one. A teammate may have just made it.
- Write each app's `--project <team>/<slug>` into that package's own upload script, the first app's too, and into the script of an app that was already set up without one: once the repo has two projects of one framework, a signed-in upload without `--project` can't tell which one it is. Always use the `<team>/<slug>` form. CI is unaffected: an upload with the project's key and a matching `--project` is accepted.
- At the end, list every app with its project's link (each upload printed one).
- If the person says only the first: set it up, and at the end list the others with "ask me again to add them".

**Several apps, with a key** (step 0 gave you one): a key names one project and can't create one. Set up the app the key is for (the app the person is working in, else the one at the repo root, else the first under `apps/`), and at the end list the others: each needs its own project, made at uiverify.ai/onboarding ("Create a project"), whose setup line the person pastes to you.

Any refusal that asks a question the person hasn't answered (which team, whether an existing project is this one): show it to the person and wait. Never pick a team, never run again without the `--project` you were using, and pass `--confirm-new <code>` only for a new project the person agreed to.

## 3. Install it

Download the quickstart for that framework with curl, the same way as this guide, and read all of it: its code is what you copy. Use only the sections that install the packages, add the config and run the capture and upload. Skip the sections on accepting, "Catch a change locally", skills, MCP, the GitHub App and "Wire it into CI": the steps below cover what is needed now.

- Storybook: https://uiverify.ai/docs/quickstart-storybook.md
- Playwright: https://uiverify.ai/docs/quickstart-playwright.md
- Bun: https://uiverify.ai/docs/quickstart-bun.md
- Vitest: https://uiverify.ai/docs/quickstart-vitest.md
- Screenshot: https://uiverify.ai/docs/quickstart-screenshot.md

Install packages with the repo's own package manager, the one its lockfile belongs to. Where a quickstart shows `npm i -D`, a pnpm, Yarn or Bun repo runs `pnpm add -D`, `yarn add -D` or `bun add -d` instead, so the repo never gets a second lockfile.

Vitest, when the repo has no Vitest browser-mode tests yet (no tests, tests in Node or jsdom, or tests in another runner such as Jest):

- The person's existing tests keep passing with their existing command, and that setup is not changed beyond excluding the new visual test files if its patterns would pick them up.
- Install the quickstart's packages, with the browser renderer for the app's framework in place of `vitest-browser-react` when the app is not React. Their versions must fit what the repo already has:
  - No `vitest` yet: add `vitest` to the same install, and `vite` too when the repo has none (Yarn installs no peer dependencies, so name them). Leave an existing `vite` as it is.
  - `vitest` 4 or later: install `@vitest/browser-playwright` at exactly that version (`@vitest/browser-playwright@<the installed vitest version>`), since it requires the same version, and leave `vitest` and `vite` as they are.
  - `vitest` older than 4, or a `vite` older than the `vitest` you would install accepts (its `vite` peer range): stop and ask the person before upgrading either. Browser mode on the Playwright provider needs Vitest 4 or later.
- The visual tests run in Vitest browser mode with `uiverifyPlugin()` in their own config, which picks up only the visual test files and carries the app's Vite plugins and path aliases but none of its unit-test settings. A repo not built with Vite (Next.js, for example) instead installs its framework's Vite plugin, such as `@vitejs/plugin-react`, at a version whose `vite` peer range includes the repo's `vite`, adds it to that config, and repeats its path aliases there. A `test:visual` package script runs the visual tests. Use that script wherever the quickstart says `npx vitest run`.
- Write a few visual tests so the first build has something to capture. Start with leaf components; for whole pages, see the quickstart's "Visual tests for whole pages" section.
- Then check that the existing test command still passes.

Screenshots (a native app), from the quickstart above:

- The folder you upload is filled by a capture that runs right before the upload, into a folder it empties first and that git ignores. Use a harness the repo already has that produces PNGs on each run, copying them into that folder when it saves them elsewhere (the quickstart's React Native example copies Maestro's out of its run folder); otherwise add one: the quickstart's swift-snapshot-testing helper for iOS, a Maestro flow like that example for Android and React Native. Save the capture as a script in the repo that empties the folder and runs it, and run that script before this setup's upload: every later build and CI run it the same way, so the same screens come out every time.
- Never upload PNGs that are already in the repo or left over from an earlier run: a snapshot library's committed reference images, a folder of screenshots, test results. They are whatever some past run saved, often of screens that no longer look that way or no longer exist, and no command reproduces them.
- If the repo already has snapshot tests, reuse their views and fixtures in the new capture, and leave those tests and their reference images as they are.
- Capture the app's main screens, the ones its top-level navigation reaches (usually 3 to 10), on one device, in one theme and one language. Not every variant: each theme, language or text size multiplies every build. At the hand-over, say which variants they could add.
- Follow the repo's own rules for running its tests (run them in a worktree, take the simulator lock, use its scheme or script): that is how you run the capture here, not a reason to stop or to ask whether to continue. Stop only when the capture can't run on this machine at all (no simulator or emulator, no Xcode): then never upload other images in its place. Tell the person what the capture needs and wait until they make it possible, then run it and carry on.

## 4. Upload one build now, from this machine

Run the capture and upload commands from the quickstart (for screenshots, the capture script from step 3), signed in from step 0 (or with the key as `UIVERIFY_API_KEY`, if step 0 gave you one), with the `--project` steps 0 and 2 say to pass, and add `--exit-zero-on-changes` to the upload. No CI or GitHub App is needed for this. If the repo has its own rules for running its tests (a worktree, a simulator lock), follow them: they are how the capture runs here, not a reason to skip the upload.

A signed-in upload prints a project line, `Created team <team> and project <team>/<slug>: <url>`, `Created project <team>/<slug>: <url>` or `Project <team>/<slug>: <url>`: keep the first one you see for the hand-over (step 7). If a signed-in upload is refused because the account can't be used for uploads (not signed in, the login expired), that is a login that can't finish: step 0, item 3 applies.

The upload waits until every screenshot has rendered, which can take several minutes: give it a long timeout or run it in the background. Once it has printed "Build uploaded:", the build is in, unless its result then reports the build failed for its project type or blocked at the plan's limit (a refusal: see Rules). Never upload again because the command was cut off or is still waiting.

A first build is all new screenshots, so the CLI reports it as changes waiting for review. That is the expected result, not a failure. Ignore its "For the agent that opened this PR" section during setup: don't accept, deny or triage anything.

## 5. Install the skills

Install the UI Verify skills for the framework you set up, so you can change UI safely, write cheap stable visual tests, preview an edit's visual impact before pushing, and review builds yourself:

Storybook:

```bash
npx skills add uiverify/uiverify \
  --skill making-ui-changes \
  --skill economical-visual-tests \
  --skill triage-visual-changes \
  --skill check-visual-changes \
  --skill storybook-visual-testing
```

Playwright:

```bash
npx skills add uiverify/uiverify \
  --skill making-ui-changes \
  --skill economical-visual-tests \
  --skill triage-visual-changes \
  --skill check-visual-changes \
  --skill playwright-visual-testing
```

Bun:

```bash
npx skills add uiverify/uiverify \
  --skill making-ui-changes \
  --skill economical-visual-tests \
  --skill triage-visual-changes \
  --skill check-visual-changes \
  --skill bun-visual-testing
```

Vitest:

```bash
npx skills add uiverify/uiverify \
  --skill making-ui-changes \
  --skill economical-visual-tests \
  --skill triage-visual-changes \
  --skill check-visual-changes \
  --skill vitest-visual-testing
```

Screenshot:

```bash
npx skills add uiverify/uiverify \
  --skill making-ui-changes \
  --skill triage-visual-changes \
  --skill check-visual-changes
```

Then add this rule to the repo's AGENTS.md and CLAUDE.md, so you read the making-ui-changes skill before any UI change from now on: `Before changing any component, page, or styles, read the making-ui-changes skill and follow it - reuse before you create, add/update the story or capture in the same change, check the blast radius on shared components, and prove the change with a visual test.`

If step 2 set up several apps, also add one line per app to the same files, since a signed-in `uiverify check` without `--project` can't tell the repo's projects apart either: `In <path>, pass --project <team>/<slug> to every uiverify upload and uiverify check.`

## 6. Connect the UI Verify MCP

The MCP lets you read builds and review changes from here. Its config holds no secret: the person logs in to UI Verify in their browser once. Follow the block for the agent you are. The blocks are written to the person (where one says I or me, that means the person), so leave the login and any commit they mention to the person.

Claude Code: Run in your project root. It adds UI Verify to your committed .mcp.json, so your whole team gets it. Then run /mcp in Claude Code, pick uiverify, and log in to UI Verify in your browser.
claude mcp add --scope project --transport http uiverify \
  https://uiverify.ai/mcp

Cursor: Add to .cursor/mcp.json and commit it to share. Then log in to UI Verify from Cursor's MCP settings.
{
  "mcpServers": {
    "uiverify": { "url": "https://uiverify.ai/mcp" }
  }
}

GitHub Copilot in VS Code: Add to .vscode/mcp.json and commit it to share. VS Code then asks you to log in to UI Verify in your browser.
{
  "servers": {
    "uiverify": { "type": "http", "url": "https://uiverify.ai/mcp" }
  }
}

Codex: Adds UI Verify to your Codex config, so it works in every project. Codex then opens the UI Verify login in your browser.
codex mcp add uiverify --url https://uiverify.ai/mcp

Gemini CLI: Run in your project root, in a folder you've trusted in Gemini CLI. It adds UI Verify to .gemini/settings.json; commit it to share with your team. Then run /mcp auth uiverify in Gemini CLI and log in to UI Verify in your browser.
gemini mcp add --transport http uiverify https://uiverify.ai/mcp

Any other agent: add UI Verify to your MCP config as a streamable HTTP server at https://uiverify.ai/mcp. It asks me to log in to UI Verify in my browser the first time it connects.

## 7. Hand over

Keep it short: sum up what you changed in the repo in a line or two (packages, config, edited files), not a list per file, and give the command for later captures. The one exception is the list of files a framework switch owes when the person may want to revert it (item 2 and the Rules say when).

The setup link is the project link from step 4's project line followed by `/onboarding` (for `Project acme/web: https://uiverify.ai/dashboard/teams/acme/projects/web`, `https://uiverify.ai/dashboard/teams/acme/projects/web/onboarding`): the page that shows the first build, where the person accepts it, then walks them through the rest (for a project whose setup they already finished, it is the project's setup recipe instead, which is why the build link goes in your message too). With several apps, use the first app's. With no project line (an upload with a key), use the build link the upload printed.

Sending the person to UI Verify, where item 1 says to: if the line you were given says "My UI Verify setup page is open.", open nothing: tell them the UI Verify page they have open shows their first build once it arrives, and give the build link if the upload printed one, in case they closed that page. Otherwise open the setup link in their browser, once (`open <url>` on macOS, `xdg-open <url>` on Linux, `start "" <url>` on Windows), and tell them you opened their project in UI Verify, with the setup link and the build link (when the upload printed one) in your message. If that command fails or there is no desktop (a remote machine, a container), give them the link to open instead.

Tell the person, in this order:

1. How the first build went, by the first of these that applies. Every screenshot failed to render on your last upload (after the one retry the Rules allow): say what failed and what you tried, and don't send them to accept anything. The command was cut off before its result: say the first build may still be arriving, and send them to UI Verify to see whether it did (with no setup link and no build link, tell them to open their project in UI Verify). Otherwise the first build is in: send them to UI Verify, where they accept the screenshots and it walks them through the rest.
2. What else you found: other frameworks from step 1, other apps from step 2 (with each project's link, as step 2 says), and the `test:visual` script or screenshot capture script if you added one (it is the command for every later capture). Each other app or framework gets its own UI Verify project.
   If you set up another framework instead of the Storybook the line named, say which and why. When the upload's result shows the build rendered its screenshots, add "Your UI Verify project is now a <framework> project."; if the command was cut off before its result, say instead that the project's framework follows the first upload that goes through, and their setup page shows it. If they wanted Storybook added to this repo, list what you changed for the other framework so they can revert it, and tell them to create a new UI Verify project and paste its setup line followed by "Use Storybook even though this repo has none."
3. Restart you (or reload the window) so the skills and the MCP load, then log in to UI Verify when the MCP asks (the block above says how). Then give them the exact sentence to type to you: "Show me the latest UI Verify build of <team>/<slug>.", with the project from step 4's project line or the line's "My UI Verify project is ..."; with neither, "Show me UI Verify build <the build id from the build link>."; with no build link either, "Show me my latest UI Verify build." That first look at a build over the MCP is also what ticks the MCP step on their setup page.
4. Offer the next step: once they have accepted the screenshots, you can make a small UI change and show them UI Verify catching it. Checking every pull request in CI comes after that, and their setup page walks them through both.
