Percy "percy: command not found" / exec fails in CI

By Daniel Zoghalchali·Latchkey

The shell could not find a percy executable. The @percy/cli package is either not installed in the job, installed for a different tool version, or not resolvable on PATH, so percy exec fails before any snapshot runs.

What this error means

A step fails with "percy: command not found" or "npm ERR! could not determine executable to run" when invoking Percy. Local runs work because the CLI is installed globally there.

/home/runner/work/_temp/script.sh: line 1: percy: command not found
Error: Process completed with exit code 127.

Common causes

@percy/cli not installed in the CI job

The dependency is present on the developer machine but missing from package.json or not installed, so CI has no percy binary.

Percy invoked as a bare command instead of via npx

Calling percy exec directly relies on it being on PATH; a locally installed CLI is only reachable through the package runner.

How to fix it

Install the CLI and run it through npx

Add @percy/cli as a dev dependency and invoke it with npx so the locally installed binary resolves.

npm install --save-dev @percy/cli
npx percy exec -- npx playwright test

Match the SDK to the CLI major version

Percy SDKs must match the CLI major version. Install the matching pair so the exec entrypoint exists.

npm install --save-dev @percy/cli @percy/playwright

How to prevent it

• Add @percy/cli and the matching SDK to devDependencies.
• Invoke Percy with npx percy exec, not a bare percy.
• Keep the CLI and SDK major versions aligned.

Frequently asked questions

Related guides

References

• GitHub Actions documentation