As we've transitioned ReadMe docs to being 100% backed by Git, we needed our own file- and folder-based format for docs. We have that format documented, but what was sorely needed was a way to make sure everything was in the right format before pushing, both locally and in your CI.
Plus, a lot of people are using Claude Code or Codex to write docs! Having a CLI tool means the AI can ask questions, understand the format, lint at the end, and make sure everything is ready to go live.
To use the CLI, just run npx @readme/cli.
Lint your docs
Linting will run through all your docs and check that your frontmatter is valid and pages are where they're supposed to be.
It searches for:
- Broken links
- Duplicate slugs
- Empty pages
- Invalid YAML
- Invalid MDX-ish
- Broken recipes
- Content that won't be shown
- Unknown properties
- Misspelled properties
- Folder structure
- Sidebar nesting limits
- Badly formed slugs
- Missing _order.yaml
- Stale _order.yaml
- Missing MDX components
Don't worry about fixing it all yourself, though. You can run with --fix, and we'll do our best for anything deterministic. For things that are more complicated, you can route it through Claude, which can make sure things are valid.
Keep OpenAPI specs in sync
There's also OpenAPI Spec files in each repo, which are linked to Markdown pages. Sometimes, as the OAS file changes, the docs get out of date. The linter can make sure things stay in sync, and pages are created for any new endpoints.
This runs as part of the linter, but it can also be accessed directly:
Lint on every PR
If you use a CI tool, you can easily make the linting run on every push. You can set it up manually, or we have helper scripts to set it up for the following tools:
npx @readme/cli setup:githubnpx @readme/cli setup:github --blacksmithnpx @readme/cli setup:gitlabnpx @readme/cli setup:bitbucketnpx @readme/cli setup:rwxnpx @readme/cli setup:circleciOnce it's set up, the linter runs against your docs on every PR and posts the results as a comment. Anything deterministic can be autofixed by running the linter with --fix.
Preview your docs locally
Currently in beta, you can run a server locally and see what your docs look like. It'll hot-reload, so you can see changes as they're happening. Over the next few weeks, as we get more stable, this will come out of beta.
Working with AI
We built the CLI to work well with AI. When you run it inside Claude Code or Codex, it adapts its output for an agent rather than a human, which means you can use it for both drafting new pages from scratch and cleaning up linting errors across an existing repo.
The CLI has deep knowledge of the folder structure, docs formats and built-in MDX components. It can handle validation, OAS syncing, and structural rules.
Writing from scratch works best when you give Claude a rough outline and let @readme/cli lint enforce the house style as it goes. You can tell Claude what to write, or add existing unformatted docs into the repo and tell it to format them. Each page it writes gets linted on save, and Claude will iterate against the warnings until the file is clean. Because the CLI knows about ReadMe-specific things like custom blocks, frontmatter requirements, and link integrity, you don't need to babysit conventions you'd otherwise have to spell out.
npx @readme/cli lint and fix any errors or warnings until it passes clean. Match the tone and structure of existing pages in the same folder.Fixing linting errors is even simpler. It's exactly the kind of work AI is great at. After you run npx @readme/cli lint yourself, you can let Claude fix the issues. The --fix flag handles the auto-fixable stuff, and everything else (broken links, missing frontmatter, malformed custom blocks, vague headings) that needs judgment can be handled by AI. Re-run lint after each batch of fixes so the agent can confirm progress and catch any regressions it introduced.
npx @readme/cli lint and fix every error and warning it reports. Start with npx @readme/cli lint --fix to handle the auto-fixable ones, then work through the rest manually. Re-run lint after each file to verify the fix landed and didn't break anything else. Don't change content beyond what's needed to resolve each issue.The old rdme tool
We also have an older CLI called rdme, from before our docs were backed by Git. It does things like upload files to ReadMe via our API, which has since been replaced by Git bidirectional sync. The old one is still available, though, for folks who've been using it.
Try it out!
Run npx @readme/cli help any time to see everything the CLI can do:
The CLI tool is all open source, so check it out on GitHub. Please file an issue if you hit a bug or have a feature request.
Happy writing!
P.S. I've also heard rumors that you can make a little friend if you run npx @readme/cli play.
ReadMe Docs Lint
my-requests.mdAskAI.mdLLMstxt.mdupgrading-to-rdme10.mdcreate-a-component.mdnpx @readme/cli lint --fixlocally to automatically fix some of these issues.