ReadMe CLI

A command-line tool for writing, previewing, and managing your ReadMe docs from your terminal.

We want feedback! If you need a new feature or find a bug, please open an issue.

Commands

Linting

Checks your docs for errors: things like invalid frontmatter, missing files, duplicate slugs, and more. Handy for catching issues before you push.

npx @readme/cli lint [--fix] [--json]

Use --fix to automatically fix what it can, or --json for machine-readable output (great for CI).

OpenAPI Sync

Syncs your reference/ directory with your OpenAPI spec. It'll create, update, or remove pages based on your spec's operations.

npx @readme/cli oas:sync

Import

Imports content from an external folder and converts it into ReadMe's format using Claude. Great for migrating existing docs.

npx @readme/cli import

Versions

Lists all your doc versions and their branches.

npx @readme/cli versions

Dev Server

Very early beta! This command is still a work in progress, and doesn't use our rendering engine yet.

Starts a local dev server so you can preview your docs as you write them. Watches for changes and refreshes automatically.

npx @readme/cli dev

GitHub Action

This repo also publishes itself as a GitHub Action, so a workflow can run lint, oas:validate, or oas:sync directly, pinned to a version, without an npx install step on every run:

- uses: readmeio/cli@v1
  with:
    readme: oas:sync

The readme input is the same command you'd run on the CLI, e.g. lint, oas:validate --dereference, or oas:sync. Each command exits non-zero on a real problem, same as running it locally, and publishes its results as step outputs — has-errors, skipped-count, total-errors, and more (see action.yml for the full list) — so a later step can check them directly instead of parsing log output:

- name: Sync reference pages from OpenAPI specs
  id: sync
  uses: readmeio/cli@v1
  with:
    readme: oas:sync

- if: steps.sync.outputs.skipped-count != '0'
  run: echo "::error::oas:sync skipped a page — see the sync step above."

Note: the first run of a workflow using this Action installs one extra dependency (@readme/markdown) behind the scenes before your command runs — this is expected, and only adds a few seconds.

Feedback

If something doesn't work right, or if you have suggestions, please open an issue. We're actively building this and want to hear from you.