DocFresh is a local-first CLI that checks whether README and docs examples still match the repository they describe.
It scans markdown files for local links, file references, package script commands, README package metadata, and explicitly marked smoke examples. It does not call hosted services, phone home, or run arbitrary commands by default.
Install the CLI from npm:
npm install -g @rogerchappel/docfresh
docfresh --helpOr run it without a global install:
npx @rogerchappel/docfresh --helpFor local development:
npm install
npm run build
node dist/cli.js --helpCheck the current repository:
docfresh checkCheck another local repository and print JSON:
docfresh check --root fixtures/valid-docs --format jsonRun opted-in smoke examples:
docfresh check --root fixtures/valid-docs --smokeRun a copy-pasteable fixture demo that builds the CLI and captures both text and JSON reports:
bash examples/check-valid-docs-demo.shSmoke commands only run when the fenced block is explicitly marked:
```sh docfresh: smoke
node --version
```- Broken local markdown links such as
[Guide](docs/missing.md). - Backticked file references such as
src/index.ts. - Documented package commands such as
npm run buildorpnpm check. - Basic README install and usage coverage for package repositories.
- Failing commands in fenced blocks marked with
docfresh: smokewhen--smokeis enabled.
Text output is optimized for terminal review:
docfresh check --root fixtures/stale-docsJSON output is stable enough for scripts and agents:
docfresh check --root fixtures/stale-docs --format jsonDocFresh exits with 0 when no error findings are present and 1 when documentation drift is found.
Generate pass/fail JSON reports from the checked-in fixtures:
bash demo/run-json-drift-demo.shThe script writes .docfresh-demo/valid-docs.json and
.docfresh-demo/stale-docs.json so reviewers can inspect both sides of the
drift signal. See JSON Drift Report Demo
for the walkthrough.
npm run check
npm test
npm run build
npm run smoke
bash scripts/validate.shexamples/basicpasses.examples/staleintentionally fails.fixtures/valid-docs,fixtures/stale-docs, andfixtures/smoke-failback the automated tests.demo/run-docfresh-basic.shruns a short README freshness demo and verifies the JSON report for the passing fixture.bash examples/run-docfresh-demo.shruns a fixture-backed freshness demo and checks a JSON report.
Run the fixture-backed demo to capture passing, stale, JSON, and smoke-check outputs:
bash demo/readme-smoke-check.shSee docs/tutorials/readme-smoke-gate.md for a pull request workflow that starts with regular docs drift checks and adds opted-in smoke commands.
For a fixture-backed demo that writes both a clean JSON report and a stale text report, run:
bash demo/readme-drift-smoke.shSee the README drift demo for a walkthrough script and promotion-safe talking points.
Run a passing fixture and capture text and JSON reports:
bash examples/check-valid-docs-demo.shRun the stale-docs fixture and confirm DocFresh reports review-worthy drift:
bash demo/stale-docs-report.shCompare a clean README fixture with a thin README that needs install and usage metadata:
bash demo/readme-readiness-gate.shSee docs/tutorials/readme-readiness-gate.md for a pre-release docs review workflow.
For promotion or screencast prep, see
docs/promo/stale-docs-video-brief.md.
For a runnable CI-style drift check, see CI Docs Drift Check:
bash demo/ci-docs-drift.shFor a pre-PR demo that writes both passing and stale-docs reports to a temporary directory:
npm run build
bash demo/run-docs-sweep.shSee docs/tutorials/pre-pr-docs-sweep.md for the walkthrough and docs/promo/social-hooks.md for grounded promotion copy.
Inspired by markdown link checkers, README smoke tests, and docs-as-tests practices. Reframed for local developer-tool repos and agent-generated documentation.
See CONTRIBUTING.md. Keep changes local-first, fixture-backed, and free of telemetry.
See SECURITY.md. Do not include secrets in fixtures, examples, tests, or issue reports.
Run the same checks expected before opening or cutting a release:
npm run check
npm run test
npm run build
npm run smoke
npm run package:smoke
npm run release:checkUse npm pack --dry-run to confirm the published package contains the CLI/runtime files plus README, license, security, support, and release notes.
Use Node.js 20 or newer. Run these checks before opening a PR:
npm run build
npm run check
npm test
npm run smoke
npm run package:smoke
npm run release:checkMIT