Note These docs are for the forthcoming v8 release. You can view the docs for the current release (v7.5.0) here.

📖 rdme

rdme is ReadMe's official command-line interface (CLI) and GitHub Action wrapper. It allows you to sync OpenAPI and Swagger definitions with projects you create on ReadMe. You can also access other parts of ReadMe's RESTful API, including syncing Markdown documentation with your project and managing project versions.

Configuration

Setup

Note These setup instructions are for CLI usage only. For usage in GitHub Actions, see GitHub Actions below.

We recommend installing rdme in your project rather than doing a global installation so you don't run into unexpected behavior with mismatching versions. 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, we recommend using npx (which is included if you have npm installed) to prefix all of your CLI commands. 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 usage in CI environments (GitHub Actions, CircleCI, Travis CI, etc.) or if you're working with multiple ReadMe projects, we recommend providing your project API key via the --key option (instead of the configuration file authentication described below).

For local CLI usage with a single project, you can authenticate rdme to your ReadMe project. This will save your API key to a local configuration file (~/.config/configstore/rdme-production.json) so you will not have to provide the --key option to commands that require it.

rdme login

rdme whoami is also available to you to determine who you are logged in as, and to what project, as well as rdme logout for logging out of that account.

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.

GitHub Actions

Note For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out our docs.

For usage in GitHub Actions, create a new GitHub Workflow file in the .github/workflows directory of your repository and add the following steps to your workflow:

- uses: actions/checkout@v3
- uses: readmeio/rdme@XX
  with:
    rdme: [your command here]

The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command:

rdme openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID

To execute this command via GitHub Actions, the step would look like this:

- uses: readmeio/rdme@XX
  with:
    rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID

Note that the @XX in the above examples refers to the version of rdme. You can see examples featuring the latest version in our docs. We recommend pointing to a fixed version, as opposed to pointing to something like the main branch, which could unexpectedly break your workflows. We also recommend configuring Dependabot to keep your actions up-to-date.

OpenAPI / Swagger

ReadMe supports OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.x.

The following examples use JSON files, but rdme supports API Definitions that are written in either JSON or YAML.

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 see the raw JSON output of any of the openapi command examples below, supply the --raw flag.

Uploading a New API Definition to ReadMe

This will upload path-to-openapi.json to your project and return an ID and URL for you to later update your file, and view it in the client.

rdme openapi [path-to-file.json]

If you want to bypass the prompt to create or update an API definition, you can pass the --create flag:

rdme openapi [path-to-file.json] --version={project-version} --create

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.

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 [path-to-file.json] --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 [path-to-file.json] --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 [path-to-file.json] --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 [path-to-file.json] --version={project-version} --update

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

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 without uploading it to ReadMe, which can be useful when constructing or editing your API definition.

rdme openapi:validate [path-to-file.json]

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. 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 [path-to-file.json]

The command will ask you a couple questions about how you wish to reduce the file and then do so. And as with the openapi command, you can also omit the file path.

Docs

Syncing a Folder of Markdown Docs to ReadMe

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.

rdme docs path-to-markdown-files --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.

Cleanup

If you wish to delete documents from ReadMe that are no longer present in your local directory, pass the --cleanup option to the command.

Edit a Single ReadMe Doc on Your Local Machine

rdme docs:edit <slug> --version={project-version}

Syncing a Single Markdown File to ReadMe

rdme docs:single path-to-markdown-file --version={project-version}

Changelogs

Syncing a Folder of Markdown to ReadMe

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.

rdme changelogs path-to-markdown-files

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.

Syncing a Single Markdown File to ReadMe

rdme changelogs:single path-to-markdown-file

Custom Pages

Syncing a Folder of Custom Pages to ReadMe

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.

rdme custompages path-to-markdown-files

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.

Syncing a Single Custom Page to ReadMe

rdme custompages:single path-to-markdown-file

Versions

Get All Versions Associated With Your Project

rdme versions

Get All Information About a Particular Version

rdme versions --version={project-version}

If you wish to see the raw JSON output from our API in this response, supply the --raw flag.

Create a New Version

rdme versions:create <version>

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

For example:

rdme versions:create <version> --fork={version-fork} --main={true|false} --beta={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 more information.

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.