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

OpenAPI Bundle

Combines a spec that's split across multiple files (external $refs to partials) into a single self-contained file. Handy when your spec is assembled at build time and you want to drop the result into reference/ from CI.

npx @readme/cli oas:bundle path/to/openapi.yaml --out reference/api.json

Without --out, the bundled spec is printed to stdout. The output format follows the --out extension (.yaml/.yml for YAML, JSON otherwise). This command works from any directory, so you can run it in your API's source repo.

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.