{"id":13406316,"url":"https://github.com/readmeio/rdme","last_synced_at":"2026-05-01T01:03:43.370Z","repository":{"id":38802191,"uuid":"109453493","full_name":"readmeio/rdme","owner":"readmeio","description":"ReadMe's official command-line interface (CLI) and GitHub Action 🌊","archived":false,"fork":false,"pushed_at":"2025-05-14T00:54:52.000Z","size":36042,"stargazers_count":122,"open_issues_count":18,"forks_count":46,"subscribers_count":19,"default_branch":"next","last_synced_at":"2025-05-14T02:34:15.826Z","etag":null,"topics":["docs","openapi","readme","swagger","sync"],"latest_commit_sha":null,"homepage":"https://docs.readme.com/main/docs/rdme","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/readmeio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-11-04T00:06:29.000Z","updated_at":"2025-05-12T19:31:49.000Z","dependencies_parsed_at":"2024-02-14T20:02:41.161Z","dependency_job_id":"df54b23e-3987-4c93-a95c-916457263cd1","html_url":"https://github.com/readmeio/rdme","commit_stats":{"total_commits":1258,"total_committers":28,"mean_commits":44.92857142857143,"dds":0.8354531001589826,"last_synced_commit":"6f59c59b5a9da5334c5a8c0616c325779fb58acc"},"previous_names":[],"tags_count":408,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readmeio%2Frdme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readmeio%2Frdme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readmeio%2Frdme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/readmeio%2Frdme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/readmeio","download_url":"https://codeload.github.com/readmeio/rdme/tar.gz/refs/heads/next","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059391,"owners_count":22007757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","openapi","readme","swagger","sync"],"created_at":"2024-07-30T19:02:26.982Z","updated_at":"2026-05-01T01:03:43.360Z","avatar_url":"https://github.com/readmeio.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","TypeScript"],"sub_categories":[],"readme":"[![rdme](https://user-images.githubusercontent.com/8854718/195465739-0f0f83d5-2e18-4e6c-96ae-944e3bb6880a.png)](https://readme.com)\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://readme.com\"\u003eReadMe\u003c/a\u003e's official command-line interface (CLI) and \u003ca href=\"#github-actions-configuration\"\u003eGitHub Action\u003c/a\u003e 🌊\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://npm.im/rdme\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/rdme?style=for-the-badge\" alt=\"NPM Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://npm.im/rdme\"\u003e\u003cimg src=\"https://img.shields.io/node/v/rdme?style=for-the-badge\" alt=\"Node Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://npm.im/rdme\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/rdme?style=for-the-badge\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/readmeio/rdme\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/readmeio/rdme/ci.yml?branch=main\u0026style=for-the-badge\" alt=\"Build status\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://readme.com\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/readmeio/.github/main/oss-badge.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nWith `rdme`, you can manage your API definition (we support [OpenAPI](https://spec.openapis.org/oas/v3.1.0.html), [Swagger](https://swagger.io/specification/v2/), and [Postman](https://schema.postman.com/)) and sync it to your API reference docs on ReadMe.\n\nNot 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.\n\n\u003e [!NOTE]\n\u003e If you're using [ReadMe Refactored](https://docs.readme.com/main/docs/migration), 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](https://github.com/readmeio/rdme/blob/v10/documentation/migration-guide.md).\n\n# Table of Contents\n\n\u003c!--\nThis section is autogenerated using `oclif` and is regenerated with every release.\n\nIf you wish to preview these changes locally, run the following:\n\n```\nnpm run build \u0026\u0026 npm run build:docs\n```\n--\u003e\n\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- toc --\u003e\n* [Table of Contents](#table-of-contents)\n* [Quick Start](#quick-start)\n* [CLI Configuration](#cli-configuration)\n* [GitHub Actions Configuration](#github-actions-configuration)\n* [Command Topics](#command-topics)\n\u003c!-- tocstop --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n# Quick Start\n\nInstall the CLI ([see here for more setup options](#setup)):\n\n```sh\nnpm install -g rdme\n```\n\nValidate an OpenAPI file in your working directory or any subdirectories ([see here for all command topics](#command-topics)):\n\n```sh\nrdme openapi validate\n```\n\nEvery command has a help page, which you can access in [our docs](./documentation/commands) or via the CLI:\n\n```sh\nrdme openapi validate --help\n```\n\nTo view the current version of `rdme` (helpful for troubleshooting and bug reports):\n\n```sh\nrdme --version\n```\n\n# CLI Configuration\n\n## Setup\n\n\u003e [!NOTE]\n\u003e These setup instructions are for CLI usage only. For usage in GitHub Actions, see [GitHub Actions Configuration](#github-actions-configuration) below.\n\n\u003cimg align=\"right\" src=\"https://img.shields.io/node/v/rdme.svg?style=for-the-badge\u0026label=\" alt=\"Node Version\"\u003e\n\nTo install the `rdme` CLI, you'll need to have [Node.js](https://nodejs.org) installed. Node.js comes bundled with [the `npm` CLI](https://github.com/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.\n\n### Installing `rdme` to Your Local Machine\n\nThe simplest way to use `rdme` is to install it globally:\n\n```sh\nnpm install -g rdme\n```\n\nWith 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](#authentication) section below).\n\n### Installing `rdme` to a Project\n\nThe 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:\n\n```sh\nnpm install rdme --save-dev\n```\n\nOnce 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:\n\n```sh\nnpx rdme openapi validate [file]\n```\n\nTo ensure you're getting the latest features and security updates, we recommend using a tool like [Dependabot](https://docs.github.com/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates) to keep `rdme` (and your other dependencies) up-to-date.\n\n## Authentication\n\nFor 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.\n\n\u003e [!WARNING]\n\u003e 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.\n\nYou can also pass in your API key via environment variable. Here is the order of precedence when passing your API key into `rdme`:\n\n1. The `--key` option. If that isn't present, we look for...\n1. The `RDME_API_KEY` environment variable. If that isn't present, we look for...\n1. The `README_API_KEY` environment variable. If that isn't present, we look for...\n1. The API key value stored in your local configuration file (i.e., the one set via `rdme login`)\n\n`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`.\n\n### 1Password\n\nAs a secure alternative to the `rdme login` approach to using the CLI locally, [1Password](https://1password.com/) users can set up the [ReadMe shell plugin](https://developer.1password.com/docs/cli/shell-plugins/readme/). 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:\n\nhttps://user-images.githubusercontent.com/8854718/208739413-590aa265-072d-4800-bca1-27f281448017.mp4\n\nTo set this up, check out [1Password's documentation on the ReadMe shell plugin](https://developer.1password.com/docs/cli/shell-plugins/readme/).\n\n## Proxy\n\n`rdme` makes API requests to the ReadMe API, which is located at [dash.readme.com](https://dash.readme.com). If you need to configure a proxy for these requests, you can do so by setting the `HTTPS_PROXY` environment variable.\n\n```sh\nexport HTTPS_PROXY=https://proxy.example.com:5678\nrdme login\n```\n\n# GitHub Actions Configuration\n\n`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:\n\n```yml\n## Required in order for the GitHub Action to access your repo's contents\n- uses: actions/checkout@v4\n\n## Runs the `rdme openapi validate petstore.json` command with the root directory being your repo\n- uses: readmeio/rdme@v10\n  with:\n    rdme: openapi validate petstore.json\n```\n\nFor more information on getting started with GitHub Actions, check out [our docs](https://docs.readme.com/main/docs/rdme#github-actions-usage).\n\n\u003c!-- (commenting all of this out until we add back this flag to all of the relevant commands)\n\nFor usage in [GitHub Actions](https://docs.github.com/actions), you can create a new GitHub Actions workflow file by installing the CLI on your local machine and running the the command you wish to run in GitHub Actions, along with the `--github` flag. For example:\n\n```sh\nrdme openapi validate --github\n```\n\nThis will run through the `openapi validate` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you. 🪄\n\nYou can see examples featuring the latest version in [our docs](https://docs.readme.com/main/docs/rdme#github-actions-examples). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot). \n\n--\u003e\n\n\u003c!--\nThis section is autogenerated using `oclif` and is regenerated with every release.\n\nIf you wish to preview these changes locally, run the following:\n\n```\nnpm run build \u0026\u0026 npm run build:docs\n```\n--\u003e\n\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- commands --\u003e\n# Command Topics\n\n* [`rdme autocomplete`](documentation/commands/autocomplete.md) - Display autocomplete installation instructions.\n* [`rdme changelog`](documentation/commands/changelog.md) - Upload Markdown files to the Changelog section of your ReadMe project.\n* [`rdme custompages`](documentation/commands/custompages.md) - Upload Markdown or HTML files to the Custom Pages section of your ReadMe project.\n* [`rdme docs`](documentation/commands/docs.md) - Upload Markdown files to the Guides section of your ReadMe project.\n* [`rdme help`](documentation/commands/help.md) - Display help for rdme.\n* [`rdme login`](documentation/commands/login.md) - Login to a ReadMe project.\n* [`rdme logout`](documentation/commands/logout.md) - Logs the currently authenticated user out of ReadMe.\n* [`rdme openapi`](documentation/commands/openapi.md) - Manage your API definition (e.g., syncing, validation, analysis, conversion, etc.). Supports OpenAPI, Swagger, and Postman collections, in either JSON or YAML formats.\n* [`rdme plugins`](documentation/commands/plugins.md) - List installed plugins.\n* [`rdme reference`](documentation/commands/reference.md) - Upload Markdown files to the Reference section of your ReadMe project.\n* [`rdme whoami`](documentation/commands/whoami.md) - Displays the current user and project authenticated with ReadMe.\n\n\u003c!-- commandsstop --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003e [!IMPORTANT]\n\u003e You'll notice that several previous `rdme` commands are no longer present. That's because this version is for projects that use [ReadMe Refactored](https://docs.readme.com/main/docs/migration) and [bi-directional syncing](https://docs.readme.com/main/docs/bi-directional-sync) is the recommended approach for most workflows previously managed via `rdme`. See more in [our migration guide](./documentation/migration-guide.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadmeio%2Frdme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freadmeio%2Frdme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freadmeio%2Frdme/lists"}