markdownlint "command not found" in CI

By Kaveh Alemi·Latchkey

The shell could not find a markdownlint (or markdownlint-cli2) executable on PATH because it was never installed on the runner. The step exits 127 before any file is checked.

What this error means

A docs-lint step fails with "markdownlint: command not found" and "Process completed with exit code 127", even though the config file is present.

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

Common causes

The tool is not installed on the runner

GitHub-hosted runners do not ship markdownlint. Without an install step or a dependency in package.json, the binary is absent.

Installed locally but not exposed to the step

A devDependency exists but the step calls the bare binary instead of npx, so PATH does not include node_modules/.bin.

How to fix it

Install the CLI, then run it

Install markdownlint-cli2 globally or as a dev dependency and invoke it via npx so PATH resolves.

- run: npm install -g markdownlint-cli2
- run: markdownlint-cli2 "**/*.md"

Use the maintained action instead of a bare binary

The official action installs and runs the tool for you, avoiding PATH issues.

- uses: DavidAnson/markdownlint-cli2-action@v16
  with:
    globs: '**/*.md'

How to prevent it

• Add markdownlint-cli2 as a devDependency and call it with npx.
• Prefer the maintained action, which installs the tool itself.
• Pin the version so the binary and rule set stay reproducible.

Frequently asked questions

Related guides

References

• GitHub Actions documentation