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.
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.
If you wish to get more information about any command within rdme
, you can execute rdme help <command>
or rdme <command> --help
. You an also execute rdme help
to see a global list of commands that rdme
offers.
--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.
With rdme
, you have access to a variety of tools to manage your API definition, most of which don't require an account on ReadMe. These tools include:
- Syncing ๐ฆ
- Validation โ
- Reduction ๐
- Inspection ๐
- Conversion โฉ
rdme
supports OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.x.
You can also pass in Postman Collections. Postman Collections are converted to OpenAPI using postman-to-openapi
prior to any syncing/validation/etc.
The following examples use JSON files, but rdme
supports API Definitions that are written in either JSON or YAML.
rdme openapi
locates your API definition (if you don't supply one), validates it, and then syncs it to your API reference on ReadMe.
Note
The rdme openapi
command supports both OpenAPI and Swagger API definitions.
If you wish to programmatically access any of this script's results (such as the API definition ID or the link to the corresponding docs in your dashboard), supply the --raw
flag and the command will return a JSON output.
This command also has a dry run mode, which can be useful for initial setup and debugging. You can perform a dry run by supplying the --dryRun
flag.
If you run rdme
within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. rdme
will then look for JSON or YAML files (including in sub-directories) that contain a top-level openapi
or swagger
property.
Note
rdme
will not scan anything in the following:
- Any
.git/
directories (if they exist) - Any files/directories specified in
.gitignore
files (including any.gitignore
files in subdirectories, if they exist)
rdme openapi
This will upload the API definition at the given URL or path to your project and return an ID and URL for you to later update your file, and view it in the client.
rdme openapi [url-or-local-path-to-file]
If you want to bypass the prompt to create or update an API definition, you can pass the --create
flag:
rdme openapi [url-or-local-path-to-file] --version={project-version} --create
This will edit (re-sync) an existing API definition (identified by --id
) within your ReadMe project. This is the recommended approach for usage in CI environments.
rdme openapi [url-or-local-path-to-file] --id={existing-id}
You can additionally include a version flag, specifying the target version for your file's destination. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments.
rdme openapi [url-or-local-path-to-file] --version={project-version}
If you wish to use the version specified in the info.version
field of your API definition, you can pass the --useSpecVersion
option. For example, say the info
object of your API definition looks like this:
{
"version": "1.2.3",
"title": "Single Path",
"description": "This is a slimmed down single path version of the Petstore definition."
}
You can pass in the --useSpecVersion
option, which would be equivalent to passing in --version=1.2.3
:
rdme openapi [url-or-local-path-to-file] --useSpecVersion
You can add --update
to the command so if there's only one API definition for the given project version to update, it will select it without any prompts:
rdme openapi [url-or-local-path-to-file] --version={project-version} --update
By default, rdme
bundles all references with paths based on the directory that rdme
is being run in. You can override the working directory using the --workingDirectory
option, which can be helpful for bundling certain external references (see here for an example file).
rdme openapi petstore.json --workingDirectory=[path to directory]
You can also perform a local validation of your API definition (no ReadMe account required!), which can be useful when constructing or editing your API definition.
rdme openapi:validate [url-or-local-path-to-file]
Similar to the openapi
command, you can also omit the file path.
We also offer a tool that allows you to reduce a large API definition down to a specific set of tags or paths (again, no ReadMe account required!). This can be useful if you're debugging a problematic schema somewhere, or if you have a file that is too big to maintain.
rdme openapi:reduce [url-or-local-path-to-file]
The command will ask you a couple questions about how you wish to reduce the file and then do so. If you wish to automate this command, you can pass in CLI arguments to bypass the prompts. Here's an example use case:
- The input API definition is called
petstore.json
- The file is reduced to only the
/pet/{id}
path and theGET
andPUT
methods - The output file is called
petstore.reduced.json
Here's what the resulting command looks like:
rdme openapi:reduce petstore.json --path /pet/{id} --method get --method put --out petstore.reduced.json
As with the openapi
command, you can also omit the file path.
This tool can also perform a comprehensive analysis (again, no ReadMe account required!) of your API definition to determine how it's utilizing aspects of the OpenAPI Specification (such as circular references, polymorphism, etc.) and any ReadMe-specific extensions you might be using.
rdme openapi:inspect [url-or-local-path-to-file]
This command contains a --feature
flag so you can filter for one or several specific features. If you pass in one or more --feature
flags, the command returns a 0
exit code if your definition contains all of the given features and a 1
exit code if your definition lacks any of the given features.
rdme openapi:inspect [url-or-local-path-to-file] --feature circularRefs --feature polymorphism
As with the openapi
command, you can also omit the file path.
You can also convert any Swagger or Postman Collection to an OpenAPI 3.0 definition.
rdme openapi:convert [url-or-local-path-to-file]
Similar to the openapi
command, you can also omit the file path.
Note
All of our OpenAPI commands already do this conversion automatically, but in case you need to utilize this exclusive functionality outside of the context of those, you can.
The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your front matter.
Passing in a path to a directory will also sync any Markdown files that are located in subdirectories. The path input can also be individual Markdown files.
rdme docs [path] --version={project-version}
This command also has an alias called guides
:
rdme guides [path] --version={project-version}
This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode in our docs.
If you wish to delete documents from ReadMe that are no longer present in your local directory:
rdme docs:prune [path-to-directory-of-markdown]
Run with --confirm
to bypass the confirmation prompt (useful for CI environments).
This command also has an alias called guides:prune
:
rdme guides:prune path-to-directory-of-markdown
The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your front matter.
Passing in a path to a directory will also sync any Markdown files that are located in subdirectories. The path input can also be individual Markdown files.
rdme changelogs [path]
This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode in our docs.
Custom Pages has support for both Markdown and HTML files. These files will require YAML front matter with certain ReadMe documentation attributes. Check out our docs for more info on setting up your front matter.
Passing in a path to a directory will also sync any HTML/Markdown files that are located in subdirectories. The path input can also be individual HTML/Markdown files.
rdme custompages [path]
This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode in our docs.
rdme versions
rdme versions --version={project-version}
rdme versions:create <version>
If you wish to automate the process of creating a new project version, and not have the CLI prompt you for input, you can do so by supplying the necessary flags to versions:create
. The best way to ensure that you have supplied all the necessary flags is by running the command locally and verifying that the CLI does not prompt you.
For example, the following command contains all the flags to bypass the CLI prompts:
rdme versions:create <version> --fork={version-fork} --main={true|false} --beta={true|false} --deprecated={true|false} --hidden={true|false}
See rdme versions:create --help
for a full list of flags.
rdme versions:update <version>
Like versions:create
, if you wish to automate this process and not be blocked by CLI input, you can supply the necessary flags to this command. See rdme versions:update --help
for a full list of flags.
You can remove a specific version from your project, as well as all of the attached specs
rdme versions:delete <version>
rdme categories --version={project-version}
rdme categories:create <title> --categoryType={category-type} --version={project-version}
categoryType
is required and must be set to either guide
or reference
If you want to prevent the creation of a duplicate category with a matching title
and categoryType
, supply the --preventDuplicates
flag.
If you are logged in, this will open the project in your browser:
rdme open
We are continually expanding and improving the offerings of this application as we expand our public API and are able. Some interactions may change over time, but we will do our best to retain backwards compatibility.