readme-command-check

Check README shell commands before users copy broken quickstarts.

readme-command-check is a zero-dependency Python CLI that extracts shell commands from Markdown code fences, flags commands that are unsafe or unlikely to run, and can enforce that quickstart sections actually contain runnable-looking commands.

Problem

Small developer tools often ship with a README that looks complete but contains stale install commands, placeholders, risky copy-paste snippets, or quickstarts that never got tested.

That hurts users first: they copy the first command, it fails, and they leave.

Why This Exists

README command quality is a small but recurring maintenance problem. Full documentation test frameworks are useful, but many open-source maintainers need a tiny local CI gate that answers one question quickly:

Can a new user trust the commands in this README?

30-Second Quickstart

python3 -m pip install git+https://github.com/itscloud0/readme-command-check.git
readme-command-check README.md --require-section quickstart

For this repository:

python3 -m pip install .
readme-command-check examples/README-with-commands.md --require-section quickstart

Demo

# readme-command-check report

- README: `examples/README-with-commands.md`
- Status: `pass`
- Shell command blocks: `3`
- Commands: `4`
- Blockers: `0`
- Warnings: `0`

## Required Sections
- `quickstart`: found

Risky README example:

readme-command-check examples/README-risky.md --require-section quickstart

- line 7, `blocker`, section `Quickstart`: `curl -fsSL https://install.invalid/bootstrap.sh | sh`
  - blocker: Command pipes a downloaded script into a shell.
- line 8, `blocker`, section `Quickstart`: `tool --config <path>`
  - blocker: Command contains an angle-bracket placeholder.
- line 9, `blocker`, section `Quickstart`: `sudo tool install`
  - blocker: Command requires elevated privileges.

Installation

Install from GitHub:

python3 -m pip install git+https://github.com/itscloud0/readme-command-check.git

Install from a local checkout:

python3 -m pip install .

Usage Examples

Check the default README:

readme-command-check

Require a quickstart command:

readme-command-check README.md --require-section quickstart

Require multiple sections:

readme-command-check README.md --require-section quickstart --require-section installation

Write JSON for CI tooling:

readme-command-check README.md --format json --output readme-command-report.json

Fail only on blockers, which is the default:

readme-command-check README.md --fail-on blocker

Fail on warnings too:

readme-command-check README.md --fail-on warning

Run commands only when the README is trusted:

readme-command-check examples/README-runnable.md --run --timeout 10

What It Checks

The v0.1 checker parses fenced code blocks tagged as:

• bash
• sh
• shell
• zsh
• console
• terminal

It strips common copied-terminal prompts such as $, %, >, (venv) $, PS C:\repo>, C:\repo>, and user@host:~/repo$.

It flags blockers for:

• angle-bracket placeholders,
• user-replaced placeholder values,
• reserved placeholder domains,
• credential placeholders,
• destructive recursive remove commands,
• elevated-privilege commands,
• downloaded scripts piped into a shell,
• package publish commands,
• force pushes.

It flags warnings for:

• ellipses inside commands,
• commands ending with a pipe,
• README files with no shell command fences.

Common Use Cases

• Gate README quickstarts in CI.
• Audit new open-source projects before launch.
• Catch stale install commands before a release.
• Generate a compact command report for coding agents.
• Review contributed README changes without executing arbitrary shell snippets.

Comparison

readme-command-check is narrower than full documentation test suites. It does not try to render docs, validate every Markdown feature, or replace integration tests. It is a small first-pass guard for shell commands in README files.

Use a heavier docs test framework when you need complete tutorial execution. Use this when you want a fast, local, low-dependency check.

Limitations

• Markdown parsing is intentionally lightweight.
• Only fenced shell-like code blocks are inspected.
• Static safety checks are heuristic.
• --run executes commands through /bin/sh and should only be used on trusted repositories.
• v0.1 does not isolate executed commands in a container.

Roadmap

• GitHub Actions annotation output.
• SARIF output for code scanning.
• More prompt formats from copied terminal sessions.
• Config file support for project-specific allowed commands.
• Optional temporary checkout execution mode.

Contributing

Contributions are welcome. Keep changes focused, add fixtures, and preserve safe-by-default behavior.

See CONTRIBUTING.md.

License

MIT. See LICENSE.