{"id":17462,"library":"rdme","title":"ReadMe CLI","description":"rdme is the official command-line interface (CLI) and GitHub Action for ReadMe, designed to streamline API documentation workflows. It enables users to manage and synchronize API definitions (supporting OpenAPI, Swagger, and Postman specifications) with their API reference documentation hosted on ReadMe.com. Beyond ReadMe-specific integrations, it provides robust API definition validation tools that can be used independently, without requiring a ReadMe account. The current stable version is v10.6.2, with active development indicated by frequent patch and minor releases, often with pre-release (`-next`) versions for upcoming features. A key differentiator is its dual functionality as both a local development tool and an automation agent for CI/CD environments, specifically via GitHub Actions. It has a notable distinction between v9 and v10 regarding compatibility with 'ReadMe Refactored' documentation experiences.","status":"active","version":"10.6.2","language":"javascript","source_language":"en","source_url":"https://github.com/readmeio/rdme","tags":["javascript","api","apidoc","apis","documentation","microservice","oai","oas","openapi"],"install":[{"cmd":"npm install rdme","lang":"bash","label":"npm"},{"cmd":"yarn add rdme","lang":"bash","label":"yarn"},{"cmd":"pnpm add rdme","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primarily a CLI tool; programmatic execution via 'run' is available but less common than direct CLI usage. Takes an array of command arguments, e.g., `run(['openapi', 'validate', 'my-spec.yaml'])`.","symbol":"run","correct":"import { run } from 'rdme'"},{"note":"Provides programmatic access to the `rdme openapi upload` functionality for syncing API definitions to ReadMe. This is less common for typical application development, more for custom automation scripts.","symbol":"upload","correct":"import { upload } from 'rdme'"},{"note":"Offers programmatic OpenAPI/Swagger validation. Useful for integrating specification linting into custom build processes or tools that don't rely on the full CLI context.","symbol":"validate","correct":"import { validate } from 'rdme'"}],"quickstart":{"code":"import { validate, run } from 'rdme';\n\nasync function quickstart() {\n  console.log('--- Validating an OpenAPI specification programmatically ---');\n  try {\n    // Assuming 'openapi.yaml' exists in the current directory\n    await validate(['openapi.yaml']); \n    console.log('OpenAPI specification is valid!');\n  } catch (error) {\n    console.error('Validation failed:', error.message);\n    // For a real application, you might exit with an error code here.\n  }\n\n  console.log('\\n--- Running a CLI command programmatically ---');\n  try {\n    // Simulate `rdme openapi validate openapi.yaml`\n    // Note: 'run' may suppress console output for success by default,\n    // or throw on error. Error handling is crucial.\n    console.log('Attempting to run `rdme openapi validate` via `run()`...');\n    await run(['openapi', 'validate', 'openapi.yaml']);\n    console.log('CLI command executed successfully via `run()`.');\n  } catch (error) {\n    console.error('CLI command failed:', error.message);\n  }\n\n  console.log('\\n--- Typical CLI usage via npm ---');\n  console.log('To install globally: npm install -g rdme');\n  console.log('Then, validate: rdme openapi validate openapi.yaml');\n}\n\n// Create a dummy openapi.yaml for demonstration purposes\nimport * as fs from 'node:fs';\nif (!fs.existsSync('openapi.yaml')) {\n  fs.writeFileSync('openapi.yaml', `\nopenapi: 3.0.0\ninfo:\n  title: My API\n  version: 1.0.0\npaths:\n  /items:\n    get:\n      summary: Retrieve items\n      responses:\n        '200':\n          description: A list of items\n`)\n}\n\nquickstart();","lang":"typescript","description":"Demonstrates programmatic usage of `rdme` for OpenAPI validation and general CLI execution, alongside typical command line installation and usage."},"warnings":[{"fix":"Determine if your ReadMe documentation project uses 'ReadMe Refactored'. If not, use `npm install -g rdme@9` or pin your project's dependency to a `9.x.x` version. Consult the official migration guide in the `rdme` GitHub repository for details.","message":"Major architectural changes in `rdme@10` make it incompatible with older ReadMe documentation platforms. If you are not using 'ReadMe Refactored', you must stick to `rdme@9` or earlier to avoid issues.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Upgrade your Node.js environment to version 20.10.0 or later using a tool like `nvm` (Node Version Manager) or by downloading the latest LTS from the Node.js website.","message":"The `rdme` CLI now requires Node.js version 20.10.0 or higher. Older Node.js versions will prevent the CLI from running.","severity":"breaking","affected_versions":"<10.6.0"},{"fix":"Review your ReadMe content for any embedded JavaScript in frontmatter and refactor it to use supported ReadMe features or static content. This change is a security enhancement.","message":"As of v10.6.0, JavaScript execution in frontmatter has been disabled for security reasons. Relying on this feature in your ReadMe content will result in unexpected behavior or errors.","severity":"gotcha","affected_versions":">=10.6.0"},{"fix":"Ensure you are using `rdme@10.5.3` or a later version if you depend on the `--working-directory` flag for OpenAPI uploads.","message":"The `--working-directory` flag for OpenAPI uploads was temporarily broken or missing in some v10.5.x releases and was restored in v10.5.3.","severity":"gotcha","affected_versions":">=10.5.0 <10.5.3"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `rdme` globally using `npm install -g rdme`. If already installed, ensure your npm global bin directory is included in your system's PATH environment variable.","cause":"The `rdme` package is not installed globally or is not in your system's PATH.","error":"command not found: rdme"},{"fix":"Upgrade Node.js to version 20.10.0 or newer. Use `nvm install 20 && nvm use 20` or download the latest LTS version from nodejs.org.","cause":"Your current Node.js version does not meet the minimum requirement for `rdme`.","error":"Error: Node.js vX.Y.Z is not supported. Please upgrade to Node.js v20.10.0 or higher."},{"fix":"Log in using `rdme login` or provide your API key via the `--key` flag or `RDME_API_KEY` environment variable. Your API key can be found in your ReadMe dashboard.","cause":"Commands requiring interaction with ReadMe.com (e.g., `openapi upload`, `docs create`) need authentication.","error":"Error: You are not authenticated with ReadMe. Please provide a ReadMe API key."},{"fix":"Use `rdme openapi validate <filename>` to get detailed error messages and fix the issues in your OpenAPI definition. Tools like VS Code with OpenAPI extensions can also help.","cause":"The specified file has syntactical or structural errors according to the OpenAPI/Swagger specification.","error":"Error: 'openapi.yaml' is not a valid OpenAPI/Swagger definition."}],"ecosystem":"npm","meta_description":null}