@uicheck-cli/cli

Check any website for responsive, accessibility, form and launch problems, from CI or your terminal. The command waits for the result, prints the quality gate, the score and the top findings with a link to the full report, and exits non-zero when the gate fails, so a broken deploy fails the build.

Works on any stack (WordPress, Next.js, React, Angular, static HTML): UICheck checks the rendered page, never your source code.

On UICheck (recommended for CI)

Nothing to install besides Node 18 or newer. The check runs on UICheck, on every screen size of your plan, and is compared with your earlier checks of the same pages.

1. Create a CI token in UICheck → Integrations → CI tokens.
2. Save it as the secret UICHECK_TOKEN in your CI.
3. Run:

npx @uicheck-cli/cli run --url https://staging.example.com

A saved project (its pages, screen sizes, settings and staging login):

npx @uicheck-cli/cli run --project client.com --env staging

GitHub Actions:

- run: npx @uicheck-cli/cli run --url https://staging.example.com
  env:
    UICHECK_TOKEN: ${{ secrets.UICHECK_TOKEN }}

Ready-made steps for GitHub Actions, GitLab CI and Bitbucket Pipelines: https://uicheck.app/help/ci

Options

| Option | | |---|---| | --url <url...> | Pages to check (repeat for more) | | --project <domain> | A project saved in UICheck, e.g. client.com | | --env <name> | production (default) or staging, with --project | | --token <token> | CI token, or set UICHECK_TOKEN (better: it stays out of the log) | | --crawl | Check the whole site from the first URL (Lens, Prism) | | --viewports <list> | e.g. 390x844,1280x800; default: your plan's standard sizes | | --browser <name> | chromium, webkit (Safari) or firefox (Safari, Firefox: Lens, Prism) | | --fail-on <level> | gate (default), or fail on any critical, major or minor finding | | --branch, --commit | Shown on the check; read from GitHub, GitLab and Bitbucket when omitted | | --timeout <minutes> | Stop waiting after this long (default 20); the check keeps running | | --server <url> | Another UICheck address (or UICHECK_SERVER); default https://uicheck.app | | --json | Print the full result as JSON |

Exit codes

| Code | | |---|---| | 0 | Passed: the quality gate passed (or nothing at your --fail-on level) | | 1 | Failed: the gate failed, or the site couldn't be checked | | 2 | UICheck couldn't be reached, or the token was refused |

On GitHub Actions the result also goes into the job summary.

Inside Playwright tests

Check the screens a link can't reach: after login, a full cart, a step of checkout, an open menu. The page is checked as it is and left untouched, so the test carries on.

npm install --save-dev @uicheck-cli/cli

import { test } from '@playwright/test';
import { uicheck } from '@uicheck-cli/cli/playwright';

test('checkout', async ({ page }) => {
  await page.goto('/cart');
  await page.click('text=Checkout');
  await uicheck(page);                                   // checks this screen, logged in
  await uicheck(page, { label: 'payment step', failOn: 'major' });
});

• With UICHECK_TOKEN set, every screen of one test run (a CI build, or one playwright test) lands in one check with the branch and commit, each screen named after its test or label. Lens uploads 50 screens per test run, Prism 500; on Free the findings are only printed.
• failOn: 'critical' (default), 'major', 'minor' or false. UICheck being unreachable never fails a test.
• Other options: hide, mask (selectors), token, server, quiet. Returns the score, the findings and the report link.
• Checks layout, text, overlaps, tap targets, images and accessibility at the test's screen size; checks that type, tab or submit are left out so the test isn't disturbed.

With AI assistants (MCP)

uicheck mcp is an MCP server, so Claude Code, Cursor, VS Code, Windsurf and Claude Desktop can check pages, read the findings (with the CSS fix UICheck tested), fix the code and check again.

claude mcp add uicheck --env UICHECK_TOKEN=uck_ci_… -- npx -y @uicheck-cli/cli mcp

Other assistants take the same command in their MCP settings ("command": "npx", "args": ["-y", "@uicheck-cli/cli", "mcp"]). Without UICHECK_TOKEN the checks run on your machine, which also reaches localhost. Tools: run_check, get_check, list_findings, get_finding, rescan, what_changed, list_checks, list_projects. Setup for each assistant: https://uicheck.app/help/mcp

On your machine (no account)

Without a token the checks run locally in a real browser (Node 20.9 or newer). Everything comes with the package; the browser (about 150 MB) is downloaded automatically the first time, once per machine.

npx @uicheck-cli/cli run --url https://example.com --viewports 390x844,1280x800

Local files work too (--url ./dist/index.html). Screenshots and results.json are written to uicheck-output/; --fail-on critical (the default here) exits 1 on any critical finding. Local mode has no quality gate, history, Figma comparison or report link: those need UICheck.

| Local option | | |---|---| | --hide, --mask, --cookie-banner | Comma-separated selectors to hide, mask in screenshots, or treat as cookie banners | | --wait-for <selector> | Wait for this element first (single-page apps) | | --extra-wait <ms> | Extra wait after the page is ready | | --concurrency <n> | Pages × screen sizes checked at once (default 3) | | --out <dir> | Output folder (default uicheck-output) |

Links

• Guide: https://uicheck.app/help/ci
• Letting UICheck past Cloudflare or Vercel protection: https://uicheck.app/help/allow-uicheck
• Support: https://uicheck.app/support