Warning
These docs are for the forthcoming v9
release. You can view the docs for the current release (v8
) here.
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. You can also access other parts of ReadMe's RESTful API, including syncing Markdown documentation with your ReadMe project and managing project versions.
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.
Warning
Heads up: our new ReadMe Refactored experience doesnβt yet support rdme
. If your project is using the new ReadMe Refactored experience, we recommend enabling bi-directional syncing via Git for an even better editing experience for the technical and non-technical users on your team!
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.
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).
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.
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
.
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:
readme-1p.mp4
To set this up, check out 1Password's documentation on the ReadMe shell plugin.
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 openapi
Note
For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out our docs.
For usage in GitHub Actions, you can create a new GitHub Actions workflow file by including the --github
flag with the command you wish to run in GitHub Actions. For example:
rdme openapi --github
This will run through the openapi
command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you. πͺ
You can see examples featuring the latest version in our docs. We recommend configuring Dependabot to keep your actions up-to-date.
$ npm install -g rdme
$ rdme COMMAND
running command...
$ rdme (--version)
rdme/9.0.0-next.35 linux-x64 node-v20.18.1
$ rdme --help [COMMAND]
USAGE
$ rdme COMMAND
...
--key <string>
: The API key associated with your ReadMe project. Note that most of the commands below require API key authentication, even though the--key
flag is omitted from the examples. See the Authentication section above for more information.--version <string>
: Your project version. See our docs for more information.
rdme autocomplete
- Display autocomplete installation instructions.rdme categories
- List or create categories in your ReadMe developer hub.rdme changelogs
- Sync Markdown files to your ReadMe project as Changelog posts.rdme custompages
- Sync Markdown/HTML files to your ReadMe project as Custom Pages.rdme docs
- Sync or prune Guides pages in your ReadMe developer hub.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 versions
- Manage your documentation versions.rdme whoami
- Displays the current user and project authenticated with ReadMe.