Skip to main content
Version: Current

Command-Line-Interface (CLI)

The happo command provides all the functionality you need for running Happo tests, including CI integration. The following documentation covers all available commands and options to help you configure Happo for your specific needs.

Authentication​

The happo CLI requires authentication to communicate with the happo.io service. You can authenticate in three ways:

  1. API Key and Secret (recommended for CI and production): Provide apiKey and apiSecret in your configuration file or as environment variables. See Configuration for details.

  2. GitHub Actions OIDC token (recommended for GitHub Actions): A job with the id-token: write permission, in a repository connected to your Happo account, needs no key or secret. See Authenticating with an OIDC token.

  3. Interactive Browser Authentication: If no apiKey or apiSecret is detected, the CLI will prompt you to authenticate in your browser. This creates short-lived authentication tokens.

    Important: Interactive authentication will not work in CI environments. You must provide explicit apiKey and apiSecret values there, or use an OIDC token in GitHub Actions. See Continuous Integration for setup instructions.

    Outside a terminal, as when a coding agent runs happo for you, the CLI skips browser authentication unless HAPPO_BROWSER_AUTH is set. With it set, the CLI prints a link to sign in with, opens it in your browser when it can, and waits up to five minutes for you to sign in on the same machine:

    HAPPO_BROWSER_AUTH=1 npx happo

Installation​

In your project, install the happo package.

npm install --save-dev happo

You'll also need to add a script to package.json:

{
  "scripts": {
    "happo": "happo"
  }
}

Commands​

Default command​

Available since happo v6.0.0.

Run happo tests to generate screenshots and upload them to the remote happo.io service.

npm run happo

Wrapping command​

Available since happo v6.0.0.

Use happo as a wrapping command when using Cypress, Playwright or Vitest. This allows Happo to coordinate test execution and collect results from parallel test runs.

npm run happo -- playwright test

Use the same --nonce when using with the finalize command:

npm run happo --nonce [NONCE] -- playwright test

Finalize command​

Available since happo v6.0.0.

Finalize a Happo report for Cypress, Playwright or Vitest tests running in parallel. This command is used after parallel test execution completes to aggregate results and finalize the report. It's used in combination with the --nonce argument.

npm run happo finalize
npm run happo finalize --nonce [NONCE]

Flake command​

Available since happo v6.3.0.

List reported flakes for a project. By default, results are printed in a human-readable format, one flake per line.

npm run happo flake

Use --allProjects to list flakes across all projects:

npm run happo flake --allProjects

Output as JSON for programmatic use:

npm run happo flake --format=json

Filter and paginate results:

npm run happo flake --project=my-project --limit=10 --page=2
npm run happo flake --component=Button --variant=primary --target=chrome
npm run happo flake --sha=ff2df74c1730341240840010c7518b2c1f4b55cb

Baseline command​

Available since happo v6.23.0.

Print the SHA of the most recent report that a run with --only or --skip can borrow its excluded snapshots from, found the same way that run finds it. It prints nothing when there is no such report. Only the SHA goes to standard output, so a script can capture it.

npx happo baseline

It is not the commit a comparison compares with, and isn't meant as --beforeSha: a pull request still compares with its merge base, and borrowing from an older report doesn't change that. Use it when the commit you would naturally diff against may have no report of its own (in a repository with several Happo projects, not every project runs on every commit): compute the --only list from what changed since the commit it prints, and pass that commit with --onlyBaseSha. See Computing --only from your changes.

Options​

--config / -c​

Available since happo v6.0.0.

Specify a custom path to the Happo configuration file. By default, Happo looks for configuration files in the following order:

  • happo.config.js,
  • happo.config.mjs,
  • happo.config.cjs,
  • happo.config.ts,
  • happo.config.mts,
  • happo.config.cts,
npm run happo --config path/to/happo.config.ts

--version / -v​

Available since happo v6.0.0.

Display the version number of the Happo CLI.

npm run happo --version

--help / -h​

Available since happo v6.0.0.

Display help text with available commands and options.

npm run happo --help

--baseBranch <branch>​

Available since happo v6.0.0.

Base branch to use for comparison when the CI doesn't name one. Default: origin/main. A GitHub pull request's base, or a GitLab merge request's or Bitbucket pull request's target branch, takes precedence; --beforeSha takes precedence over all of them.

npm run happo --baseBranch origin/long-lived-branch

--link <url>​

Available since happo v6.0.0.

URL to contextualize the comparison. Default: auto-detected from CI environment.

npm run happo --link https://github.com/happo/happo/pull/123

--message <message>​

Available since happo v6.0.0.

Message to associate with the comparison. Default: on a GitHub Actions pull request or a GitLab CI merge request pipeline, the pull request's or merge request's title; otherwise the subject of the commit.

npm run happo --message "Add new feature"

--authorEmail <email>​

Available since happo v6.0.0.

Email address of the author of the comparison. Default: auto-detected from CI environment.

npm run happo --authorEmail author@example.com

--afterSha <sha>​

Available since happo v6.0.0.

"After" SHA to use for comparison. Default: auto-detected from CI environment, or HEAD SHA if not set.

npm run happo --afterSha abc123def456

--beforeSha <sha>​

Available since happo v6.0.0.

"Before" SHA to use for comparison. Default: auto-detected from CI environment.

npm run happo --beforeSha xyz789ghi012

--fallbackShas <shas>​

Available since happo v6.0.0.

Space-, newline- or comma-separated list of fallback shas for compare calls. Default: auto-detected from CI environment.

npm run happo --fallbackShas "sha1,sha2,sha3"

--fallbackShasCount <count>​

Available since happo v6.0.0.

Number of fallback shas to use for compare calls. Default: 50.

npm run happo --fallbackShasCount 100

--notify <emails>​

Available since happo v6.0.0.

One or more (comma-separated) email addresses to notify with results.

npm run happo --notify me@example.com,you@example.com

--nonce <nonce>​

Available since happo v6.0.0.

Nonce to use for Cypress, Playwright or Vitest comparison. Use the same nonce when using with the finalize command.

npm run happo --nonce my-unique-nonce -- playwright test
npm run happo finalize --nonce my-unique-nonce

--skip <json>​

Available since happo v6.10.0.

JSON array of components or story files to exclude from snapshot rendering. Defaults to an empty array (nothing skipped).

Each entry can take one of these forms:

  • { "component": "Card" } — skip all variants of a component
  • { "component": "Card", "variant": "bordered" } — skip a specific variant
  • { "storyFile": "./src/stories/Card.stories.js" } — skip all stories in a file (Storybook only)
npm run happo --skip '[{"component":"Card"},{"component":"Button","variant":"primary"}]'
npm run happo --skip '[{"storyFile":"./src/stories/Card.stories.js"}]'

See Partial runs in the Storybook guide for how to use --skip to reduce quota usage.

--only <json>​

Available since happo v6.10.0.

JSON array of components or story files to exclusively render, skipping all others. Uses the same entry format as --skip. The storyFile entry form is Storybook-only; the component form works for all integrations.

npm run happo --only '[{"component":"Card"},{"storyFile":"./src/stories/Button.stories.js"}]'

See Partial runs in the Storybook guide for how to use --only to reduce quota usage, or Local development for using it from a developer's machine.

--onlyBaseSha <sha>​

Available since happo v6.23.0.

The commit an --only list was computed from: the one your diff compared with, such as a pull request's base, or the commit the baseline command printed. Happo borrows the snapshots the list leaves out from that commit's report, and from no other, since the changes between an older report and that commit would be neither rendered nor borrowed:

  • When the commit's report is saved, Happo borrows from it.
  • When a Happo run for the commit is still in progress, Happo waits for its report, and fails the run if that one fails.
  • When the commit has neither, Happo renders every story instead of the list, and says why.
npm run happo --only '[{"storyFile":"./src/stories/Button.stories.js"}]' --onlyBaseSha "$BASE_SHA"

Without it, Happo borrows from the most recent report it can find, which may be older than the commit your list was computed from (when a run failed or was skipped, say).

--githubToken <token>​

Available since happo v6.0.0.

Removed in happo v7. The CLI no longer posts statuses as comments; happo.io posts them. See Upgrading to happo v7.

In happo v6, it was the GitHub token the CLI used to post Happo statuses as pull request comments.

Flake command options​

These options apply only to the happo flake command.

--allProjects​

Available since happo v6.3.0.

List flakes across all projects. By default, only flakes for the current project (from your config) are shown.

npm run happo flake --allProjects

--format <format>​

Available since happo v6.3.0.

Output format. Use "human" (default) for readable output or "json" for raw JSON output suitable for scripting.

npm run happo flake --format=json

--project <name>​

Available since happo v6.3.0.

Project to filter flakes for. Defaults to the project defined in your config.

npm run happo flake --project=my-project

--limit <number>​

Available since happo v6.3.0.

Maximum number of flake results to return. Default: 100. Maximum: 1000.

npm run happo flake --limit=50

--page <number>​

Available since happo v6.3.0.

Page number for paginated results. Default: 1.

npm run happo flake --page=2

--component <name>​

Available since happo v6.3.0.

Filter flakes by component name.

npm run happo flake --component=Button

--variant <name>​

Available since happo v6.3.0.

Filter flakes by variant name.

npm run happo flake --variant=primary

--target <name>​

Available since happo v6.3.0.

Filter flakes by target name (browser/viewport).

npm run happo flake --target=chrome

--sha <sha>​

Available since happo v6.3.0.

Filter flakes by a specific before/after SHA. Returns only flakes associated with that commit.

npm run happo flake --sha=ff2df74c1730341240840010c7518b2c1f4b55cb