ReadMe CLI

Common errors

• command not found: rdme

  cause The `rdme` package is not installed globally or is not in your system's PATH.
  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.

• Error: Node.js vX.Y.Z is not supported. Please upgrade to Node.js v20.10.0 or higher.

  cause Your current Node.js version does not meet the minimum requirement for `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.

• Error: You are not authenticated with ReadMe. Please provide a ReadMe API key.

  cause Commands requiring interaction with ReadMe.com (e.g., `openapi upload`, `docs create`) need authentication.
  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.

• Error: 'openapi.yaml' is not a valid OpenAPI/Swagger definition.

  cause The specified file has syntactical or structural errors according to the OpenAPI/Swagger specification.
  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.

Warnings

• breaking 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.
  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.
• breaking The `rdme` CLI now requires Node.js version 20.10.0 or higher. Older Node.js versions will prevent the CLI from running.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Ensure you are using `rdme@10.5.3` or a later version if you depend on the `--working-directory` flag for OpenAPI uploads.

Install

• npm install rdme npm
• yarn add rdme yarn
• pnpm add rdme pnpm

Imports

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

Quickstart

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();