← back to gallery

CLI Agent Score

Agent-readiness ratings for popular CLI tools from npm, Homebrew, and PyPI

dev-toolscliagent-readinessmcpdeveloper-toolsleaderboard
Open product ↗

cli-agent-score

Leaderboard that rates popular CLI tools on agent-readiness — structured output, machine-parseable errors, exit codes, and MCP support — so devtool teams know what to fix.

What it does

Scans ~100+ popular CLIs from npm, Homebrew, and PyPI registries. Analyzes their README and package metadata to score each tool on 5 axes of agent-readiness:

  1. Structured Output — does --json or --format json exist?
  2. Machine-Readable Errors — does the tool document structured error output?
  3. Exit Codes — are exit codes documented beyond 0/1?
  4. Pipe/Stdin Friendliness — does the tool support stdin, --quiet, piping?
  5. MCP Support — does an MCP server exist for this tool?

Each axis scores 0-10. Composite score is the average (0-10) mapped to a letter grade (A+ through F).

Data Sources

| Source | URL | Refresh Interval |
|--------|-----|-----------------|
| npm Registry API | https://registry.npmjs.org/{package} | Every 6 hours |
| npm Search API | https://registry.npmjs.org/-/v1/search?text=keywords:cli&size=30&quality=0.9 | Every 6 hours (discovery) |
| npm Downloads API | https://api.npmjs.org/downloads/point/last-week/{package} | Every 6 hours |
| Homebrew Formulae API | https://formulae.brew.sh/api/formula.json | Every 6 hours |
| GitHub README API | https://api.github.com/repos/{owner}/{repo}/readme | Every 6 hours (for Homebrew tools with GitHub homepages) |
| PyPI JSON API | https://pypi.org/pypi/{package}/json | Every 6 hours |

All data is fetched from public APIs at runtime. No mock or seed data.

API Endpoints

All endpoints are under /cli-agent-score.

| Method | Path | Description |
|--------|------|-------------|
| GET | /cli-agent-score/health | Health check — returns {"ok":true} |
| GET | /cli-agent-score/api/leaderboard | Paginated leaderboard. Query params: sort (total/structured/errors/exit_codes/pipe/mcp/name/installs), order (asc/desc), source (npm/brew/pypi), min_score (0-10), q (search), page, limit |
| GET | /cli-agent-score/api/tool/:slug | Single tool detail with all 5 axis scores and evidence |
| GET | /cli-agent-score/api/stats | Aggregate stats: total tools, average score, grade distribution, axis averages, worst axis |
| GET | /cli-agent-score/api/axes | Axis definitions (name, description, weight, max points) |
| POST | /cli-agent-score/api/scan/trigger | Manually trigger a re-scan (rate-limited to 1 per 10 minutes) |

How to Run Locally

npm install
PORT=4741 node server.js

Visit http://localhost:4741/cli-agent-score/ in your browser.

The initial data scan runs automatically on startup and takes ~15-30 seconds to fetch from all registries.

Stack