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. 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.

Table of Contents

• CLI Configuration
  • Setup
  • Authentication
  • Proxy
• GitHub Actions Configuration
• Usage
  • Common rdme Options
  • API Definitions 📚
  • Docs (a.k.a. Guides) 📖
  • Changelog 📣
  • Custom Pages 📄
  • Versions ⏳
  • Categories 🪣
  • Open Your ReadMe Project in Your Browser
• Future

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 the RDME_API_KEY environmental variable. Here is the order of precedence when passing your API key into rdme:

1. The --key option. If that isn't present, we look for...
2. The RDME_API_KEY environmental variable. If that isn't present, we look for...
3. 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 openapi

GitHub Actions Configuration

[!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.

Usage

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.

Common rdme Options

• --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.

API Definitions 📚

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.

Syncing an API Definition to ReadMe

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. The rdme swagger command is an alias for rdme openapi and is deprecated.

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.

Omitting the File Path

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

Uploading a New API Definition to ReadMe

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

Editing (Re-Syncing) an Existing API Definition

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}

Uploading or Editing an API Definition in a Project Version

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

Override the Working Directory

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]

Validating an API Definition

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.

Reducing an API Definition

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 the GET and PUT 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.

Inspecting an API Definition

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.

Converting an API definition

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.

Docs (a.k.a. Guides) 📖

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.

Prune

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

Changelog 📣

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 📄

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.

Versions ⏳

Get All Versions Associated With Your Project

rdme versions

Get All Information About a Particular Version

rdme versions --version={project-version}

Create a New 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} --isPublic={true|false}

See rdme versions:create --help for a full list of flags.

Update a Version

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.

Delete a Version

You can remove a specific version from your project, as well as all of the attached specs

rdme versions:delete <version>

Categories 🪣

Get All Categories Associated to Your Project Version

rdme categories --version={project-version}

Create a New Category for your 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.

Open Your ReadMe Project in Your Browser

If you are logged in, this will open the project in your browser:

rdme open

Future

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.