Your README is a promise nobody tests.

Setup instructions rot silently. You rename a script, add an env var, switch a package manager, and the quickstart keeps promising a path that stopped working weeks ago. Nobody on the team notices, because everyone who would notice already has the repo running. The only people who hit the wall are new users, and they bounce without filing an issue.

I got tired of wondering whether mine still worked, so I built a tool that checks.

What it does

coldstart stages your committed state in a temp dir. No node_modules, no .env, none of the untracked files that make it work on your machine and nowhere else. Then it parses the shell commands out of your README and replays them in order, tracking the working directory and environment between steps.

When a step fails, you get the exit code, the last output lines, and the exact README line that sent a new user there.

Static checks before anything runs

A lot of README bugs are detectable without executing a single command:

  • npm run start documented but no "start" script in package.json
  • pnpm lockfile present but the README says npm install
  • curl | bash installers, flagged because they execute on the reader's machine, not in any sandbox
  • commands that reference files the repo does not ship and the user cannot provide

What it found on my own repos

7 repos, 2 fail their own quickstart. The worst one documents npm run start and there is no start script anywhere in package.json. A reader following the README hits a wall at step 2 and leaves. That is a star I never got and never knew I lost.

Honest limits

It replays what the README documents, not what your CI does. Server-style commands get started, probed, and killed, so it can only tell you whether the app boots, not whether it works. Placeholder arguments like your-api-key get skipped with a note instead of failing.

Try it 

npx coldstart-cli # current directory npx coldstart-cli <git-url> # or straight from GitHub npx coldstart-cli --docker # real clean room in a container

Zero dependencies, Node 18+. Repo: https://github.com/princejain756/coldstart

If you run it on yours, I genuinely want to know what breaks. The weirder the README, the better the test case.