rdme

ReadMe's official command-line interface (CLI) and GitHub Action 🌊

With rdme, you can manage your API definition (we support OpenAPI, Swagger, and Postman) and sync it to your API reference docs on ReadMe.

Not using ReadMe for your docs? No worries. rdme has a variety of tools to help you identify issues with your API definition — no ReadMe account required.

[!NOTE] If you're using ReadMe Refactored, you'll want to use rdme@10 or later. If you're not using ReadMe Refactored, you'll want to use rdme@9. More info can be found in our migration guide.

Table of Contents

• Table of Contents
• Quick Start
• CLI Configuration
• GitHub Actions Configuration
• Required in order for the GitHub Action to access your repo's contents
• Runs the rdme openapi validate petstore.json command with the root directory being your repo
• Command Topics

Quick Start

Install the CLI (see here for more setup options):

npm install -g rdme

Validate an OpenAPI file in your working directory or any subdirectories (see here for all command topics):

rdme openapi validate

Every command has a help page, which you can access in our docs or via the CLI:

rdme openapi validate --help

To view the current version of rdme (helpful for troubleshooting and bug reports):

rdme --version

CLI Configuration

Setup

[!NOTE] These setup instructions are for CLI usage only. For usage in GitHub Actions, see GitHub Actions Configuration below.

To install the rdme CLI, you'll need to have Node.js installed. Node.js comes bundled with the npm CLI, which you'll need to install rdme. You can see our current Node.js version requirements in the green badge on the right.

Installing rdme to Your Local Machine

The simplest way to use rdme is to install it globally:

npm install -g rdme

With a global installation, you'll be able to run rdme within any directory on your local machine. If you log in once, you can quickly access your project without having to remember your API key (see the Authentication section below).

Installing rdme to a Project

The recommended approach for shared projects is to install rdme in your project's dependencies, that way you don't run into unexpected behavior with mismatching versions of rdme. We also suggest using the --save-dev flag since rdme is typically used as part of a CI process and is unlikely to be running in your production application:

npm install rdme --save-dev

Once installed in your project, you can use the npx prefix (which is included if you have npm installed) to run your CLI commands locally. For example:

npx rdme openapi validate [file]

To ensure you're getting the latest features and security updates, we recommend using a tool like Dependabot to keep rdme (and your other dependencies) up-to-date.

Authentication

For local CLI usage with a single project, you can authenticate rdme to your ReadMe project using rdme login. Once you follow the prompts and are successfully authenticated, your API key will be saved to a local configuration file (~/.config/configstore/rdme-production.json) and you won't have to provide the --key option to commands that require it.

[!WARNING] For security reasons, we strongly recommend providing a project API key via the --key option in automations or CI environments (GitHub Actions, CircleCI, Travis CI, etc.). It's also recommended if you're working with multiple ReadMe projects to avoid accidentally overwriting existing data.

You can also pass in your API key via environmental variable. Here is the order of precedence when passing your API key into rdme:

• The --key option. If that isn't present, we look for...
• The RDME_API_KEY environmental variable. If that isn't present, we look for...
• The README_API_KEY environmental variable. If that isn't present, we look for...
• The API key value stored in your local configuration file (i.e., the one set via rdme login)

rdme whoami is also available to you to determine who is logged in, and to what project. You can clear your stored credentials with rdme logout.

1Password

As a secure alternative to the rdme login approach to using the CLI locally, 1Password users can set up the ReadMe shell plugin. With this approach, you can store your ReadMe API key in 1Password and securely pass it in your rdme commands using biometrics. See below for a demo of this behavior:

https://user-images.githubusercontent.com/8854718/208739413-590aa265-072d-4800-bca1-27f281448017.mp4

To set this up, check out 1Password's documentation on the ReadMe shell plugin.

Proxy

rdme makes API requests to the ReadMe API, which is located at dash.readme.com. If you need to configure a proxy for these requests, you can do so by setting the HTTPS_PROXY environmental variable.

export HTTPS_PROXY=https://proxy.example.com:5678
rdme login

GitHub Actions Configuration

rdme has a thin wrapper that allows the CLI to be used as a proper action in a GitHub Actions workflow. For example, say you wanted to run rdme openapi validate petstore.json in a GitHub Actions environment. Here's what the corresponding steps would look like in a GitHub Actions workflow file:

# Required in order for the GitHub Action to access your repo's contents
- uses: actions/checkout@v4

# Runs the `rdme openapi validate petstore.json` command with the root directory being your repo
- uses: readmeio/rdme@v10
  with:
    rdme: openapi validate petstore.json

For more information on getting started with GitHub Actions, check out our docs.

Command Topics

• rdme autocomplete - Display autocomplete installation instructions.
• rdme changelog - Upload Markdown files to the Changelog section of your ReadMe project.
• rdme custompages - Upload Markdown or HTML files to the Custom Pages section of your ReadMe project.
• rdme docs - Upload Markdown files to the Guides section of your ReadMe project.
• rdme help - Display help for rdme.
• rdme login - Login to a ReadMe project.
• rdme logout - Logs the currently authenticated user out of ReadMe.
• rdme openapi - Manage your API definition (e.g., syncing, validation, analysis, conversion, etc.). Supports OpenAPI, Swagger, and Postman collections, in either JSON or YAML formats.
• rdme plugins - List installed plugins.
• rdme reference - Upload Markdown files to the Reference section of your ReadMe project.
• rdme whoami - Displays the current user and project authenticated with ReadMe.

[!IMPORTANT] You'll notice that several previous rdme commands are no longer present. That's because this version is for projects that use ReadMe Refactored and bi-directional syncing is the recommended approach for most workflows previously managed via rdme. See more in our migration guide.

Changelog

10.4.0 (2025-07-08)

Bug Fixes

• pages/upload: decouple autofixing and uploads (#1282) (d5a6fe9)
• v9/openapi: problem with FormData compositions on Node 24 (#1242) (046842f)

Features

• add legacy id flag to openapi upload (#1278) (7871f31)
• logger: improved warnings for GHA users (#1290) (ec138c5)
• mark page upload commands as stable, update migration guide (#1287) (0a03bd6)
• new custompages upload command (#1265) (dc4ceb4)
• openapi: add openapi resolve (#1063) (987e103)
• openapi: adding a warning for our experimental postman support (#1277) (ac0b068)
• support for rdme changelog upload (#1272) (fd594f3)