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 two 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. 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 or non-interactive terminals. You must provide explicit apiKey and apiSecret values for these scenarios. See Continuous Integration for setup instructions.

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 or Playwright. 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 or Playwright 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

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. Default: origin/main.

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: auto-detected from CI environment.

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

--githubToken <token>​

Available since happo v6.0.0.

GitHub token to use for posting Happo statuses as comments. Use in combination with the githubApiUrl configuration option. Default: auto-detected from environment.

npm run happo --githubToken $GITHUB_TOKEN

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