The scorecard-classic command evaluates your API descriptions against quality standards defined in your Redocly project's scorecard configuration. Use this command to validate API quality and track compliance with organizational governance standards across multiple severity levels.
The scorecard-classic command requires a scorecard configuration in your Redocly project. You can configure this in your project settings or by providing a --project-url flag. Learn more about configuring scorecards.
redocly scorecard-classic <api> --project-url=<url>
redocly scorecard-classic <api> --config=<path>
redocly scorecard-classic <api> --format=json
redocly scorecard-classic <api> --target-level=<level>
redocly scorecard-classic <api> --verbose| Option | Type | Description |
|---|---|---|
| api | string | Path to the API description filename or alias that you want to evaluate. See the API section for more details. |
| --config | string | Specify path to the configuration file. |
| --format | string | Format for the output. Possible values: stylish, json. Default value is stylish. |
| --help | boolean | Show help. |
| --project-url | string | URL to the project scorecard configuration. Required if not configured in the Redocly configuration file. Example: https://app.cloud.redocly.com/org/my-org/projects/my-project/scorecard-classic. |
| --target-level | string | Target scorecard level to achieve. The command validates that the API meets this level and all preceding levels without errors. Exits with an error if the target level is not achieved. |
| --verbose, -v | boolean | Run the command in verbose mode to display additional information during execution. |
You can use the scorecard-classic command with an OpenAPI description file path or an API alias defined in your Redocly configuration file.
redocly scorecard-classic openapi/openapi.yaml --project-url=https://app.cloud.redocly.com/org/my-org/projects/my-project/scorecard-classicIn this example, scorecard-classic evaluates the specified API description against the scorecard rules defined in the provided project URL.
By default, the CLI tool looks for the Redocly configuration file in the current working directory. Use the optional --config argument to provide an alternative path to a configuration file.
redocly scorecard-classic openapi/openapi.yaml --config=./another/directory/redocly.yamlYou can configure the scorecard project URL in your Redocly configuration file to avoid passing it as a command-line argument:
scorecard:
fromProjectUrl: https://app.cloud.redocly.com/org/my-org/projects/my-project/scorecard-classic
apis:
core@v1:
root: ./openapi/api-description.jsonWith this configuration, you can run the command without the --project-url flag:
redocly scorecard-classic core@v1To generate machine-readable output suitable for CI/CD pipelines or further processing, use the JSON format:
redocly scorecard-classic openapi/openapi.yaml --format=jsonThe JSON output is grouped by scorecard level and includes:
- version information
- achieved scorecard level
- summary of errors and warnings for each level
- rule ID and documentation link (for built-in rules)
- severity level (error or warning)
- location information (file path, line/column range, and JSON pointer)
- descriptive message about the violation
Use the --target-level option to ensure your API meets a specific quality level. The command validates that your API satisfies the target level and all preceding levels without errors:
redocly scorecard-classic openapi/openapi.yaml --target-level=GoldIf the API doesn't meet the target level, the command:
- displays which level was actually achieved
- shows all validation issues preventing the target level from being met
- exits with a non-zero exit code (useful for CI/CD pipelines)
This is particularly useful in CI/CD pipelines to enforce minimum quality standards before deployment.
For troubleshooting or detailed insights into the scorecard evaluation process, enable verbose mode:
redocly scorecard-classic openapi/openapi.yaml --verboseVerbose mode displays additional information such as:
- project URL being used
- authentication status
- detailed logging of the evaluation process
The scorecard-classic command requires authentication to access your project's scorecard configuration. You can authenticate in one of two ways:
Set the REDOCLY_AUTHORIZATION environment variable with your API key:
export REDOCLY_AUTHORIZATION=your-api-key-here
redocly scorecard-classic openapi/openapi.yamlIf no API key is provided, the command prompts you to log in interactively:
redocly scorecard-classic openapi/openapi.yamlThe CLI opens a browser window for you to authenticate with your Redocly account.
The scorecard evaluation categorizes issues into multiple levels based on your project's configuration. Each issue is associated with a specific scorecard level, allowing you to prioritize improvements.
The command displays the achieved scorecard level, which is the highest level your API meets without errors. The achieved level is shown in both stylish and JSON output formats.
When all checks pass, the command displays a success message:
☑️ Achieved Level: Gold
✅ No issues found for openapi/openapi.yaml. Your API meets all scorecard requirements.When issues are found, the output shows:
- the achieved scorecard level
- the rule that was violated
- the scorecard level of the rule
- the location in the API description where the issue occurs
- a descriptive message explaining the violation
If a --target-level is specified and not achieved, the command displays an error message and exits with a non-zero code.
lint- Standard linting for API descriptions with pass/fail resultsbundle- Bundle multi-file API descriptions into a single filestats- Display statistics about your API description structure