Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
run
✓ import { run } from 'rdme'
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'])`.
upload
✓ import { upload } from 'rdme'
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.
validate
✓ import { validate } from 'rdme'
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.
Demonstrates programmatic usage of `rdme` for OpenAPI validation and general CLI execution, alongside typical command line installation and usage.
import { validate, run } from 'rdme';
async function quickstart() {
console.log('--- Validating an OpenAPI specification programmatically ---');
try {
// Assuming 'openapi.yaml' exists in the current directory
await validate(['openapi.yaml']);
console.log('OpenAPI specification is valid!');
} catch (error) {
console.error('Validation failed:', error.message);
// For a real application, you might exit with an error code here.
}
console.log('\n--- Running a CLI command programmatically ---');
try {
// Simulate `rdme openapi validate openapi.yaml`
// Note: 'run' may suppress console output for success by default,
// or throw on error. Error handling is crucial.
console.log('Attempting to run `rdme openapi validate` via `run()`...');
await run(['openapi', 'validate', 'openapi.yaml']);
console.log('CLI command executed successfully via `run()`.');
} catch (error) {
console.error('CLI command failed:', error.message);
}
console.log('\n--- Typical CLI usage via npm ---');
console.log('To install globally: npm install -g rdme');
console.log('Then, validate: rdme openapi validate openapi.yaml');
}
// Create a dummy openapi.yaml for demonstration purposes
import * as fs from 'node:fs';
if (!fs.existsSync('openapi.yaml')) {
fs.writeFileSync('openapi.yaml', `
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths:
/items:
get:
summary: Retrieve items
responses:
'200':
description: A list of items
`)
}
quickstart();
rdme --version
Debug
Known issues
breakingMajor 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.fixDetermine 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.
affects: >=10.0.0
breakingThe `rdme` CLI now requires Node.js version 20.10.0 or higher. Older Node.js versions will prevent the CLI from running.fixUpgrade 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.
affects: <10.6.0
gotchaAs 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.fixReview 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.
affects: >=10.6.0
gotchaThe `--working-directory` flag for OpenAPI uploads was temporarily broken or missing in some v10.5.x releases and was restored in v10.5.3.fixEnsure you are using `rdme@10.5.3` or a later version if you depend on the `--working-directory` flag for OpenAPI uploads.
affects: >=10.5.0 <10.5.3
Errors
Common errors & fixes
command not found: rdme
The `rdme` package is not installed globally or is not in your system's PATH.
fixInstall `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.
Error: Node.js vX.Y.Z is not supported. Please upgrade to Node.js v20.10.0 or higher.
Your current Node.js version does not meet the minimum requirement for `rdme`.
fixUpgrade 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.
Error: You are not authenticated with ReadMe. Please provide a ReadMe API key.
Commands requiring interaction with ReadMe.com (e.g., `openapi upload`, `docs create`) need authentication.
fixLog 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.
Error: 'openapi.yaml' is not a valid OpenAPI/Swagger definition.
The specified file has syntactical or structural errors according to the OpenAPI/Swagger specification.
fixUse `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.
Audit
Dependencies
No dependency data recorded yet.