--- canonical: https://docs.jentic.com/cli/api-scorecard/ representation: markdown-alternate # Canonical page: https://docs.jentic.com/cli/api-scorecard/ # This is the Markdown alternate of the page above. --- # API Scorecard – CLI Reference The **Jentic API Scorecard CLI** scores OpenAPI Descriptions against the [Jentic API AI Readiness Framework (JAIRF)](../reference/api-readiness-framework/overview.md) across six dimensions, returning a single grade and actionable recommendations. Scoring runs entirely locally inside a Docker container — your spec never leaves your environment. --- ## Requirements - **Node.js** 20 LTS or newer (`>= 20.19.0`) with npm/npx. See [Node.js downloads](https://nodejs.org/). - **Docker** installed and running. See [Docker installation](https://docs.docker.com/get-docker/). The CLI pulls the scoring image automatically on first run. - Network access to [`ghcr.io`](https://ghcr.io) (to pull the image) and to whatever URL hosts the OpenAPI document you're scoring (the engine fetches it from inside the container). ## Quick start OpenAPI documents from [Jentic Public APIs (OAK)](https://github.com/jentic/jentic-public-apis) score without any key, uncapped — no signup, no config: ```bash npx @jentic/api-scorecard-cli@latest score \ https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/swagger-api/petstore/1.0.27/openapi.json ``` For URLs outside OAK or local files, set the API key: ```bash JENTIC_API_KEY= npx @jentic/api-scorecard-cli@latest score \ https://petstore3.swagger.io/api/v3/openapi.json ``` ```bash JENTIC_API_KEY= npx @jentic/api-scorecard-cli@latest score ./openapi.yaml ``` !!! important Free keys come with **100 scorings per month** (resets at the start of each calendar month). See [Anonymous vs keyed access](#anonymous-vs-keyed-access) for signup and quota details. That's it. The CLI pulls the scoring engine automatically on first run. ![CLI score output](https://github.com/jentic/jentic-api-scorecard/raw/main/assets/cli-screenshot.png) > **Prefer a permanent install?** See [Install](#install) below to set up the CLI globally. ## Install ```bash npm install -g @jentic/api-scorecard-cli ``` This installs the CLI globally. The scoring engine (Docker image) is downloaded automatically the first time you run `score` — allow a minute or two on a typical connection. For local files or non-OAK URLs you'll also need a `JENTIC_API_KEY` — see [Anonymous vs keyed access](#anonymous-vs-keyed-access). Verify the install: ```bash jentic-api-scorecard --version ``` > **Prefer zero-install?** You can skip the global install and use `npx` — every example in > this README works with `npx @jentic/api-scorecard-cli` in place of `jentic-api-scorecard`. > Pin to a specific release with `npx @jentic/api-scorecard-cli@` (e.g. `@1.0.0`); > the unpinned form resolves to whatever the `latest` dist-tag points at on each invocation, > while `npm install -g` pins you to the installed version until you explicitly update. ## Control output depth The `--detail` flag lets you zoom in: ```bash # Just the headline score and grade npx @jentic/api-scorecard-cli@latest score --detail summary ./openapi.yaml # Per-dimension breakdown (default) npx @jentic/api-scorecard-cli@latest score --detail dimensions ./openapi.yaml # Individual signals within each dimension npx @jentic/api-scorecard-cli@latest score --detail signals ./openapi.yaml # Full diagnostics with top 5 findings per severity npx @jentic/api-scorecard-cli@latest score --detail diagnostics ./openapi.yaml ``` ## Machine-readable output Add `--format json` to emit engine-verbatim JSON on stdout (filtered by whatever `--detail` level you pick). Pretty stays the unconditional default; `--format json` is the canonical way to get a stable machine-readable channel for CI gating, archival, or LLM-assisted review. ```bash # Gate on the headline score in CI npx @jentic/api-scorecard-cli@latest score ./openapi.yaml --format json | jq .summary.score # Capture the full evidence bundle to a file npx @jentic/api-scorecard-cli@latest score ./openapi.yaml \ --format json --detail diagnostics --output report.json ``` `--output ` (`-o`) writes the report to a path instead of stdout; the spinner stays on stderr. `--quiet` (`-q`) suppresses the stderr spinner even in interactive terminals (the spinner already auto-suppresses when stderr isn't a TTY). Engine warnings still pass through stderr. ## HTML report Add `--format html` to render an interactive, self-contained HTML scorecard — a single file with all JS and CSS inlined (no external CDN, works offline), suitable for CI artifacts and dashboards. It honours `--detail`, so `--detail diagnostics` embeds the full evidence bundle. ![HTML scorecard report](https://github.com/jentic/jentic-api-scorecard/raw/main/assets/cli-html-report.png) Because the output is a full HTML document, the CLI refuses to print it straight into an interactive terminal — redirect it or use `-o`: ```bash # Redirect to a file npx @jentic/api-scorecard-cli@latest score ./openapi.yaml --format html > scorecard.html # Or write it with -o, at full detail npx @jentic/api-scorecard-cli@latest score ./openapi.yaml \ --format html --detail diagnostics -o scorecard.html ``` ## LLM analysis Add `--with-llm` to unlock LLM-backed signals — deeper semantic reasoning about whether your API descriptions are actionable for agents, whether error responses support autonomous recovery, and more. Requires an LLM provider: cloud (OpenAI / Anthropic / Gemini / AWS Bedrock) or a local OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, …). Without `--with-llm`, the LLM-backed signals are not evaluated — they hold an assumed-perfect baseline score until `--with-llm` actually assesses them. A default (no-`--with-llm`) scorecard therefore reflects only the deterministic signals, with the LLM-backed ones sitting at that perfect baseline; turn on `--with-llm` to have them genuinely assessed (which can lower your score). ```bash export OPENAI_API_KEY=sk-... export LLM_PROVIDER=OPENAI export LIGHT_LLM_PROVIDER=OPENAI export LLM_LIGHT_MODEL=gpt-4o-mini JENTIC_API_KEY= npx @jentic/api-scorecard-cli@latest score ./openapi.yaml --with-llm ``` Token cost is low — the engine uses a lightweight model (e.g. Claude Haiku, GPT-4o-mini), processes operations in small batches, and caps at 7 batches regardless of spec size. Local models (Ollama) cost nothing per call. If the LLM calls fail (bad credentials, an inaccessible model, an unreachable endpoint), the affected LLM-backed signals get scored as perfect — which would inflate their dimension(s) and the overall score. Rather than print a misleading scorecard, the CLI **suppresses the report, names the affected signals and the provider error on stderr, and exits `8`** — so a CI job running `--with-llm` fails loudly instead of passing on an inflated score. Fix the provider error and retry, or re-run without `--with-llm` for a valid score from the non-LLM signals. See **[LLM Signals guide](https://github.com/jentic/jentic-api-scorecard/blob/main/docs/llm-signals.md)** for all provider recipes (including local Ollama), the full environment variable reference, and troubleshooting. ## Anonymous vs keyed access OpenAPI documents from [Jentic Public APIs (OAK)](https://github.com/jentic/jentic-public-apis) score without any key and stay on the free tier — those URLs bypass key validation entirely. For everything else (local files, URLs outside OAK), get a key from the [Jentic Scorecard API Keys page](https://app.jentic.com/scorecard?tab=api-keys). Then set it: ```bash export JENTIC_API_KEY= ``` Real keys are validated live by the container against `api.jentic.com`. The same call doubles as the per-key usage / rate-limit accounting hit. **Each free key gets 100 scorings per month**, resetting at the start of each calendar month. Once that quota is exhausted the CLI exits with code `7` and prints the `Retry-After` value along with a link to upgrade your plan. ## CLI reference ``` jentic-api-scorecard [-V | --version] [-h | --help] jentic-api-scorecard [options] ``` ### Commands | Command | Description | |---|---| | [`score `](#score) | Score an OpenAPI document by URL or local file path. | | [`convert `](#convert) | Reformat a saved scorecard JSON file without re-scoring. | ### `score` Score an OpenAPI document by URL or local file path. ``` jentic-api-scorecard score [options] ``` #### Arguments | Name | Description | |---|---| | `` | `http(s)://` URL or local file path to an OpenAPI document. Required. | #### Options | Flag | Default | Choices | Description | |---|---|---|---| | `--with-llm` | off | — | Enable LLM-backed analysis. Requires an LLM provider (see [LLM analysis](#llm-analysis)). | | `--bundle` | off | — | Force CLI-side bundling for URL inputs: the CLI fetches the URL on the host, bundles with Redocly, and pipes to the container via stdin. Use for URLs only the host can reach (internal networks, VPN-gated specs, auth-required URLs). Requires `JENTIC_API_KEY`. No-op for local files. | | `-d, --detail ` | `dimensions` | `summary`, `dimensions`, `signals`, `diagnostics` | Payload depth (see [Control output depth](#control-output-depth)). | | `-f, --format ` | `pretty` | `pretty`, `json`, `html`, `markdown`, `sarif` | Output encoding (`markdown` is a GitHub-flavored projection for `$GITHUB_STEP_SUMMARY` / PR comments; `sarif` projects diagnostics only as SARIF 2.1.0 for GitHub code-scanning and always emits full diagnostics regardless of `--detail`; see also [Machine-readable output](#machine-readable-output) and [HTML report](#html-report)). | | `-o, --output ` | stdout | — | Write the formatted report to ``. The spinner stays on stderr. | | `-q, --quiet` | off | — | Suppress the stderr spinner regardless of TTY. | | `-h, --help` | — | — | Show usage for `score`. | #### Environment | Variable | When | Purpose | |---|---|---| | `JENTIC_API_KEY` | URLs outside OAK and local files | Real key issued at the [Jentic Scorecard API Keys page](https://app.jentic.com/scorecard?tab=api-keys); validated live against `api.jentic.com` (see [Anonymous vs keyed access](#anonymous-vs-keyed-access)). **Free quota: 100 scorings per calendar month.** | | LLM provider + routing vars | With `--with-llm` | The CLI auto-detects credentials (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, AWS keys) and routing (`LLM_PROVIDER`, `LIGHT_LLM_PROVIDER`, `LLM_MODEL`, `LLM_LIGHT_MODEL`, `*_API_URL`, `LLM_MAX_TOKENS`) and forwards them to the container; loopback URLs are rewritten so a host-side Ollama is reachable. Full reference: [LLM Signals guide](https://github.com/jentic/jentic-api-scorecard/blob/main/docs/llm-signals.md). | #### Exit codes | Code | Meaning | |---|---| | 0 | Scoring completed (regardless of the score itself). | | 1 | Generic error (bad input, unexpected container failure, output write failure). | | 2 | Auth: `JENTIC_API_KEY` is set to a value the Jentic backend does not recognize, or a local file / stdin input was used without the key set. | | 3 | Anonymous gate rejected: URL outside the OAK allowlist and no key set. | | 4 | Docker not installed or daemon unreachable. | | 5 | Spec fetch, parse, or host-side bundling failure (local files and `--bundle` URLs). | | 6 | Engine invocation failure. | | 7 | Rate limit reached: the key is valid but the user is over quota. Message includes the server-provided `detail` and the `Retry-After` header when present. | | 8 | LLM analysis failed under `--with-llm`: the provider call failed, so the LLM-derived signals would be scored as perfect and inflate the result. The CLI suppresses the report and prints the affected signals + provider error on stderr. Re-run without `--with-llm` for a valid non-LLM score. | ### `convert` Reformat a saved scorecard JSON file without re-scoring. Useful for producing multiple output formats from a single `score` run — no Docker or API key required (a URL `` is still fetched over HTTP). ``` jentic-api-scorecard convert [options] ``` **Recommended CI recipe** (score once, format many): ```sh # Step 1 — score once and save full output jentic-api-scorecard score ./openapi.yaml --format json --detail diagnostics -o report.json # Step 2 — derive HTML and SARIF without a second Docker run jentic-api-scorecard convert report.json --format html -o scorecard.html jentic-api-scorecard convert report.json --format sarif -o results.sarif ``` > **Note:** For lossless reformatting, save at `--detail diagnostics`. A scorecard saved at a shallower detail level cannot have the missing fields recovered at `convert` time. #### `convert` arguments | Name | Description | |---|---| | `` | `http(s)://` URL or local file path to a scorecard JSON file (produced by `score --format json`). Required. | #### `convert` options | Flag | Default | Choices | Description | |---|---|---|---| | `-d, --detail ` | `dimensions` | `summary`, `dimensions`, `signals`, `diagnostics` | Payload depth applied on top of the saved level. | | `-f, --format ` | `pretty` | `pretty`, `json`, `html`, `markdown`, `sarif` | Output encoding. Same semantics as `score --format`, including the SARIF exception below. | | `-o, --output ` | stdout | — | Write the formatted report to ``. | | `-h, --help` | — | — | Show usage for `convert`. | `--format sarif` always emits the full diagnostics regardless of `--detail` (same as `score`); an explicit non-`diagnostics` `--detail` combined with `--format sarif` prints a warning on stderr rather than silently being ignored. #### `convert` exit codes | Code | Meaning | |---|---| | 0 | Conversion completed. | | 1 | Generic error (input neither a URL nor an existing file, fetch/read failure, not valid JSON, not a scorecard, output write failure). | ## Prefer a browser? [**jentic.com/scorecard**](https://jentic.com/scorecard) offers the same scoring in a web UI — paste a URL or drop a file, no Docker or Node required. --- ## Related links * [API Scoring – Getting Started](../getting-started/api-scoring.md) * [Agent Skill (Scoring)](./api-scorecard-skill.md) * [Agent Skill (Improvements)](./api-improve-skill.md) * [GitHub Action](./api-scorecard-action.md) * [Enterprise Readiness](./api-scorecard-enterprise.md) * [JAIRF Overview](../reference/api-readiness-framework/overview.md) * [jentic/jentic-api-scorecard – source and full documentation](https://github.com/jentic/jentic-api-scorecard)