Help us improve
Share bugs, ideas, or general feedback.
From api-scorecard
Scores OpenAPI documents against the Jentic API AI Readiness Framework (JAIRF) using the @jentic/api-scorecard-cli. Supports local files or URLs, produces JSON/HTML scorecards, and can integrate with CI.
npx claudepluginhub jentic/jentic-api-scorecard --plugin api-scorecardHow this skill is triggered — by the user, by Claude, or both
Slash command
/api-scorecard:jentic-api-scorecardThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`@jentic/api-scorecard-cli` is a zero-install CLI that scores an OpenAPI document
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Guides systematic root-cause debugging when tests fail, builds break, or unexpected errors occur. Provides a structured triage checklist to preserve evidence, localize, and fix issues instead of guessing.
Share bugs, ideas, or general feedback.
@jentic/api-scorecard-cli is a zero-install CLI that scores an OpenAPI document
against the Jentic API AI Readiness Framework (JAIRF) and prints a scorecard.
It runs the scoring engine locally in a Docker container that the CLI manages for
you — the spec never leaves the machine (the one exception is --with-llm, which
sends spec context to an LLM provider you choose).
Requirements: Node.js (≥ 20.19) and a running Docker daemon. The engine image is pulled automatically on first run.
This CLI has exactly one command (score) and six options (--with-llm,
--bundle, -d/--detail, -f/--format, -o/--output, -q/--quiet), plus the
built-in -h/--help and -V/--version — all listed in full below. It does not
have flags for multiple-file output directories, config files, watch mode,
batch/glob input, custom rulesets, or thresholds — do not guess or fabricate any of
these. If you are unsure whether something is supported, run
npx @jentic/api-scorecard-cli score --help and trust its output over memory.
# Zero-install (recommended for one-off scoring and CI):
npx @jentic/api-scorecard-cli@latest score <input> [options]
# Or install globally, then call the binary directly:
npm install -g @jentic/api-scorecard-cli
jentic-api-scorecard score <input> [options]
# Pin a version for reproducibility (CI) — replace <version> with a real release:
npx @jentic/api-scorecard-cli@<version> score <input> [options]
<input> is either an https:// URL or a local file path to an OpenAPI
document. Anything that is neither a URL nor an existing file exits with code 1.
Set the key as an environment variable — never on the command line:
export JENTIC_API_KEY=<your-key> # from https://app.jentic.com/scorecard?tab=api-keys
| Input | Key required? |
|---|---|
A Jentic Public APIs (OAK) raw URL (https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/...) | No — free and uncapped. |
Any other https:// URL | Yes |
| A local file | Yes |
Any input with --bundle | Yes |
Free keys allow 100 scorings per calendar month. A missing/invalid key or an exhausted quota surfaces as a distinct exit code (see Exit codes below).
# Score an allowlisted OAK URL — no key needed:
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
# Score any other URL (key required):
JENTIC_API_KEY=$KEY npx @jentic/api-scorecard-cli@latest score https://petstore3.swagger.io/api/v3/openapi.json
# Score a local file (key required):
JENTIC_API_KEY=$KEY npx @jentic/api-scorecard-cli@latest score ./openapi.yaml
# Machine-readable JSON (engine-verbatim, filtered by --detail):
JENTIC_API_KEY=$KEY npx @jentic/api-scorecard-cli@latest score ./openapi.yaml --format json
# Full evidence bundle as JSON to a file:
JENTIC_API_KEY=$KEY npx @jentic/api-scorecard-cli@latest score ./openapi.yaml \
--format json --detail diagnostics --output report.json
# Self-contained HTML report (must write to a file or redirect — refuses an interactive terminal):
JENTIC_API_KEY=$KEY npx @jentic/api-scorecard-cli@latest score ./openapi.yaml --format html -o scorecard.html
# Fetch + bundle a host-only URL (internal/VPN/auth-gated) on the host, then score (key required):
JENTIC_API_KEY=$KEY npx @jentic/api-scorecard-cli@latest score https://internal.example.com/openapi.yaml --bundle
score command surface (complete)jentic-api-scorecard score <input> [options]
| Flag | Default | Choices | What it does |
|---|---|---|---|
--with-llm | off | — | Enable LLM-backed signals. Requires an LLM provider — see references/llm-analysis.md. |
--bundle | off | — | Fetch + Redocly-bundle a URL on the host, then pipe to the engine over stdin. For URLs only the host can reach. Requires JENTIC_API_KEY. No-op for local files. |
-d, --detail <level> | dimensions | summary, dimensions, signals, diagnostics | Payload depth (see below). |
-f, --format <fmt> | pretty | pretty, json, html | Output encoding. |
-o, --output <file> | stdout | — | Write the formatted report to <file>. The progress spinner stays on stderr. |
-q, --quiet | off | — | Suppress the stderr spinner regardless of TTY. |
-h, --help | — | — | Show usage for score. |
Detail levels (cumulative depth): summary = headline score + grade only;
dimensions = adds the per-dimension breakdown (default); signals = adds
the per-signal breakdown; diagnostics = adds the full evidence/findings bundle.
In pretty format, diagnostics renders a severity tally plus the top 5 findings
per severity; use --format json --detail diagnostics for the complete bundle.
Format notes: pretty is human-readable (ANSI color on a TTY, plain text when
piped or written to a file). json is engine-verbatim, filtered by --detail.
html is a single self-contained document — it refuses to print to an
interactive terminal, so always pair it with -o <file> or redirect stdout.
In CI, provide the key as a secret and choose a machine-readable format. The process
exit code is the pass/fail signal — 0 means scoring completed (it does not
assert any minimum score; the CLI has no threshold flag, so gate on the score
yourself by parsing the JSON). For reproducible CI runs, pin @<version> to a fixed
release instead of @latest so a new publish can't shift results mid-pipeline.
# GitHub Actions example
- name: Score the OpenAPI document
env:
JENTIC_API_KEY: ${{ secrets.JENTIC_API_KEY }}
run: |
npx @jentic/api-scorecard-cli@latest score ./openapi.yaml \
--format json --output scorecard.json --quiet
For an HTML artifact to upload, swap to --format html -o scorecard.html.
--with-llm enables additional signals that an LLM evaluates. It requires LLM
provider credentials + routing variables in the environment; without them the run
fails fast with guidance. The full provider matrix (cloud providers and a local
Ollama/OpenAI-compatible recipe) and the failure semantics are in
references/llm-analysis.md — read it before constructing a --with-llm
invocation.
Check these to react correctly to failures — they are a stable contract.
| Code | Meaning | Typical fix |
|---|---|---|
| 0 | Scoring completed (regardless of the score value). | — |
| 1 | Generic error: bad input, unexpected container failure, write failure. | Check <input> is a real URL or existing file. |
| 2 | Auth: JENTIC_API_KEY unrecognized, or a local/stdin input ran without a key. | Set a valid JENTIC_API_KEY. |
| 3 | Gate rejected: a non-OAK URL with no key set. | Set a key, or use an OAK URL. |
| 4 | Docker not installed or daemon unreachable. | Start Docker. |
| 5 | Spec fetch, parse, or host-side bundling failure (local files and --bundle URLs). | Verify the spec is reachable and valid OpenAPI. |
| 6 | Engine invocation failure. | Re-run; inspect stderr. |
| 7 | Rate limited: key valid but over the monthly quota. | Wait for reset (see Retry-After) or upgrade. |
| 8 | LLM analysis failed under --with-llm. | Fix provider credentials, or re-run without --with-llm. |
JENTIC_API_KEY. Export it.-o file.html or redirect stdout.--bundle so the
CLI fetches it host-side (needs a key).--with-llm — provider credentials are wrong/unreachable; the run
is suppressed so a falsely-perfect score isn't reported. Re-run without --with-llm
for a valid non-LLM score, or fix the provider per references/llm-analysis.md.npx @jentic/api-scorecard-cli score --help. Don't invent
flags that aren't in the table above.