If a newcomer can't copy-paste your README, your docs are broken.

docs-drift checks every flag, endpoint and setting in your docs against your code, and points to the line that's wrong.

docs-drift findings: README.md line 4 documents --port, the code now declares --listen, with the rename commit 450a93d.

## Usage

rich README.md --line-number
@click.option("--line-numbers", "-n")
export APP_LOG_LEVEL=debug
GET /v1/status          → 404
tool serve --port 8000
p.add_argument("--listen")
npm run build
"workers" defaults to 4   default=8
git log -S --port  → 450a93d Rename port to listen
from client import Client; Client.connect()
files-to-prompt path/to/dir -e txt -e md
-c/--cxml   Output in Claude XML format
README.md:61   missing   --line-number
README.md:4    renamed   --port → --listen
README.md:6    default   4 → 8
docs/config.md:12   ok   timeout
uv run docs-drift scan --repo .
exit 2  Error: No such option '--line-number'.
exit 0  rich README.md --line-numbers

## Usage

rich README.md --line-number
@click.option("--line-numbers", "-n")
export APP_LOG_LEVEL=debug
GET /v1/status          → 404
tool serve --port 8000
p.add_argument("--listen")
npm run build
"workers" defaults to 4   default=8
git log -S --port  → 450a93d Rename port to listen
from client import Client; Client.connect()
files-to-prompt path/to/dir -e txt -e md
-c/--cxml   Output in Claude XML format
README.md:61   missing   --line-number
README.md:4    renamed   --port → --listen
README.md:6    default   4 → 8
docs/config.md:12   ok   timeout
uv run docs-drift scan --repo .
exit 2  Error: No such option '--line-number'.
exit 0  rich README.md --line-numbers

Code ships every day. Docs change when someone remembers.

README.md:61

rich-cli documented --line-number. The CLI only accepts --line-numbers.

— Textualize/rich-clipinned at 46f4d24

pipx install docs-drift

Rule-based and offline. No account, no API key, no code execution.

— docs-drift 0.1.0on PyPI

rich-cli's README asked for a flag the CLI never had.

Saved scan, pinned at 46f4d24

Statements checked54

Confirmed drift2

Open report

README.md:61documented

Add the --line-number
switch to enable
line numbers.

The docs tell you to type this.

__main__.py:358declared

@click.option(
  "--line-numbers",
  "-n",
)

The code accepts this.

terminalexit 2

$ rich README.md \
    --line-number
Error: No such option
'--line-number'.

What a newcomer sees.

A flag got renamed. The README never heard about it.

Synthetic fixture, real Git history

Statements checked10

Drift found5

Open report

README.md:4renamed

`serve` accepts
--port (default 8000).

Still documented.

cli.pydeclared

p.add_argument(
  "--listen",
)

What the code says now.

450a93dcommit

Rename port to listen
02 Oct 2026

- --port
+ --listen

The change that caused it.

files-to-prompt: drift caught, then fixed upstream.

Historical snapshot, pinned before the fix

Statements checked31

Upstream fixf7cf729

Open report

README.md:55documented

c/--cxml

A dropped dash in the docs.

cli.pydeclared

@click.option(
  "-c", "--cxml",
)

The real option.

f7cf729upstream

Fixed by the
maintainer later.

Other findings in this snapshot may be scanner limits.

How it works

Scan

Find every statement your code no longer supports.

Reads your Markdown, indexes argparse, Click, Typer, FastAPI, Flask, Commander and Express, and matches each claim to a real declaration. Rule-based. Your code is never run.

Try one stale claim

$ docs-drift scan

README.md:4
  renamed  --port
  → --listen
  450a93d

README.md:6
  default  4 → 8

5 findings · 10 claims

Gate

(and fail only on drift a pull request introduces)

Add the GitHub Action to CI. Reports come out as SARIF, JUnit, JSON, HTML and Markdown, and a baseline keeps old drift from blocking new work.

GitHub Action guide

docs.yml

on: [pull_request]
jobs:
  docs:
    steps:
      - uses: actions/checkout
      - uses: docs-drift
        with:
          fail-on-drift: true

Fix

Review a patch, not a guess.

docs-drift fix previews a documentation patch built from source evidence. Nothing is written without an explicit flag. VS Code shows the same findings with quick fixes.

VS Code extension

$ docs-drift fix

--- README.md
+++ README.md
@@ -4 +4 @@
-`serve` accepts --port
+`serve` accepts --listen

Apply? [y/N]

What it reads · hover a row

PythonCLI flags argparse See claims
PythonOptions & commands Click See claims
PythonOptions & commands Typer See claims
PythonRoutes FastAPI See claims
PythonRoutes Flask See claims
JavaScriptRoutes Express See claims
JavaScriptCLI flags Commander See claims
Any languageLiteral reads Environment variables See claims
npm · make · justTasks Package scripts See claims
JSON · YAML · TOMLDeclared values Settings & defaults See claims
Python · TSFunctions & classes Code symbols See claims
RepositoryLinked files File paths See claims
PythonCLI flags argparse See claims
PythonOptions & commands Click See claims
PythonOptions & commands Typer See claims
PythonRoutes FastAPI See claims
PythonRoutes Flask See claims
JavaScriptRoutes Express See claims
JavaScriptCLI flags Commander See claims
Any languageLiteral reads Environment variables See claims
npm · make · justTasks Package scripts See claims
JSON · YAML · TOMLDeclared values Settings & defaults See claims
Python · TSFunctions & classes Code symbols See claims
RepositoryLinked files File paths See claims

Coverage is partial for every framework: literal, static patterns only. Known limits →

1 / 4

What the evidence says:

“Error: No such option '--line-number'.” Exit code 2, from the exact command rich-cli's README told us to run.

Rrich-cli 1.8.1
Reproduced at README.md:61

Rules decide literal claims first. The optional model can never override a finding the code already decided.

ddocs-drift design rule
How it works

Rule-only scans never import or execute your code. They parse text and syntax trees, and ask Git for history.

SSecurity model
SECURITY.md

Two confirmed defects and two false positives in the saved sample. We publish both, because a tool you can't check is a tool you can't trust.

4rich-cli review
Saved scan, agent-assisted review

Does your documentation have trust issues?

Evidence graph linking README claims to source symbols and commits.

Generated Markdown review: documentation health 56 out of 100 with a verdict table.

Every stale flag teaches a newcomer the README can't be trusted. docs-drift checks each instruction against the code, so the next person who follows your docs runs a command that works.

Inspect the real case Scan a repo

Ready to check your docs?

Choose how you'd like to start.

Scan in the browser

Paste a public GitHub URL. No sign-in. Most small repos finish in under two minutes.

Paste a repo URL

Install the CLI

pipx install docs-drift
then run docs-drift scan in any repository.

Put your README to the test.

A public GitHub URL. A static scan. Evidence you can inspect.

docs-drift / scannerRule-based · no API key

Tryor open the instant sample →

01Reviewed caserich-cli reviewed case46f4d246Open report → 02Saved scanrich-cli46f4d246Open report → 03Historical snapshotfiles-to-prompt · historicalae06f203Open report →

Synthetic fixtures separate from real-repository evidence

One stale claim (synthetic fixture)py-cli demo fastapi-svc demo node-tool demo clean-repo demo