Backstage "backstage-cli: command not found" in CI

The backstage-cli binary is provided by the @backstage/cli dev dependency and lives in node_modules/.bin. If install did not run, dev dependencies were pruned, or a script calls it outside yarn, the shell cannot find it.

What this error means

A build or lint step fails with "backstage-cli: command not found" or "sh: backstage-cli: not found", exit code 127, even though package.json scripts reference it.

$ backstage-cli package build
/bin/sh: 1: backstage-cli: not found
error Command failed with exit code 127.

Common causes

Dependencies were not installed before the step

The job ran a script that calls backstage-cli before yarn install, so @backstage/cli is not in node_modules/.bin yet.

Dev dependencies were pruned or the call bypasses yarn

A production install (--production) drops @backstage/cli, or the command runs directly in a shell where node_modules/.bin is not on PATH.

How to fix it

Install dependencies, then run via yarn scripts

1. Run yarn install --immutable before any build step.
2. Invoke the CLI through a package.json script so yarn puts node_modules/.bin on PATH.
3. Avoid --production for the build stage that needs the CLI.

yarn install --immutable
yarn tsc
yarn build:backend

Call the CLI through yarn if invoking directly

Prefix a bare invocation with yarn so it resolves the local binary instead of searching PATH.

yarn backstage-cli package build

How to prevent it

• Always install dependencies before steps that use backstage-cli.
• Invoke the CLI through package.json scripts, not bare shell calls.
• Do not prune dev dependencies in the stage that runs the build.

Related guides