# CLI

The CLI is perfect for developers who prefer the command line or need to
integrate quality checks into their development workflow. It returns the same
lint results as the website.

## Running the CLI

Run the CLI with `npx` — no install required, always picks up the latest version:

```bash
npx rmoa lint --filename <openapi-filename> --api-key <API_KEY>
```

Prefer a global install? You can still do that:

```bash
npm install -g rmoa
rmoa lint --filename <openapi-filename> --api-key <API_KEY>
```

The rest of this page uses `npx rmoa`. Drop the `npx` if you've installed globally.

## Usage

Use the CLI to lint and get a score for your OpenAPI definition in a format
that's easy to parse and integrate with your development workflow.

### Getting an API key

The CLI calls the Rate My OpenAPI API, which requires an API key.
[Subscribe to the free plan](https://docs.ratemyopenapi.com/pricing) (free
forever) to register or log in — your API key is created automatically and is
available in your dashboard.

:::warning{title="New API keys required"}
On May 12, 2026, Rate My OpenAPI switched to a new registration system. API
keys created before that date no longer work. Subscribing again issues a new
key automatically.
:::

### Basic

Lint an OpenAPI definition in JSON or YAML format using the CLI's default
configuration:

```bash
npx rmoa lint --filename <openapi-filename> --api-key <API_KEY>
```

### Advanced

Override the minimum passing score (default 80 / 100), cap the allowed
warnings and errors, and switch the output to JSON:

```bash
npx rmoa lint \
  --filename <openapi-filename> \
  --api-key <API_KEY> \
  --minimum-score 60 \
  --max-warnings 10 \
  --max-errors 0 \
  --output json
```

### Sample output

```text
Rate OpenAPI file openapi.json
Press Ctrl+C to cancel.

✔ Loading file for processing
✔ Analyzing file

==> Results

Overall 51
======
- Docs 56
- Completeness 53
- SDK Generation 72
- Security 35
======

View details of your report at https://ratemyopenapi.com/report/c6cb55f4-143d-48ed-88d9-aa7a6a6585bb
```

:::warning{title="Reports are public"}
All reports generated by Rate My OpenAPI are public (with an unguessable UUID
URL), even when uploaded with an API key. Anyone with the URL to your report
can access it.
:::

### Commands

```bash
npx rmoa <command>

Commands:
npx rmoa lint

Lint and get a score for your OpenAPI definition using the Rate My OpenAPI ruleset

Options:
  --version        Show version number                                 [boolean]
  --help           Show help                                           [boolean]
  --api-key        Your Rate My OpenAPI API Key              [string] [required]
  --filename       The OpenAPI file name to process          [string] [required]
  --dir            The directory containing your OpenAPI file
                                                         [string] [default: "."]
  --output         default, json                   [string] [default: "default"]
  --max-warnings   The maximum number of warnings allowed before labeling the ru
                   n as failed.                                         [number]
  --max-errors     The maximum number of errors allowed before labeling the run
                   as failed.                                           [number]
  --minimum-score  The minimum score (0 - 100) to label a lint run as successful
                   /passing. Default is 80.               [number] [default: 80]
```

Source code and documentation at [zuplo/rate-my-openapi](https://github.com/zuplo/rate-my-openapi).