BotVisibility CLI — agent readiness scanner on npm

CLI Tool

CLI via npm

Scan your site and codebase for AI agent readiness. Like Lighthouse, but for AI agents.

$ npx botvisibility stripe.com
View on npm
npmjs.com/package/botvisibility

Quick start

Zero install required. Run it against any public URL to get an instant agent-readiness report.

Basic URL scan
npx botvisibility https://example.com
JSON output for CI/CD
npx botvisibility stripe.com --json
Full scan with repo analysis
npx botvisibility mysite.com --repo ./
Global install
npm install -g botvisibility

What it checks

BotVisibility runs 58 checks across five progressive levels of AI agent readiness.

L1 Discoverable — 18 checks

Can AI agents find your site and understand what it offers? Checks for llms.txt, agent cards, OpenAPI / Swagger specs, MCP server manifests, AI-specific meta tags, Link headers (RFC 8288), Content-Signals (contentsignals.org), an RFC 9727 api-catalog, Markdown content negotiation, and WebMCP. This is the foundation — if agents cannot discover you, nothing else matters.

L2 Usable — 11 checks

Once discovered, can agents actually work with your API? Validates that operations are well-defined, authentication is documented (including OpenID Connect and RFC 9728 OAuth Protected Resource metadata), error responses are structured, idempotency keys are supported, and optionally whether protected endpoints speak the x402 payment protocol. Agents need predictable interfaces.

L3 Optimized — 7 checks

Is your API efficient for agent consumption? Looks for sparse field selection, cursor-based pagination, filtering and sorting parameters, bulk operations, cache headers, and MCP tool quality. These reduce the token cost of every interaction.

L4 Indexable — 15 checks

Can AI search systems find, index, and ground answers in your site? Checks Googlebot crawl access, an explicit Google-Extended policy, homepage indexability, sitemap presence, HTTPS, mobile viewport, JSON-LD validity and entity declaration, a self-referential canonical, heading hierarchy, image alt coverage, and substantive content. These map directly to Google’s official guidance for AI Overviews and AI Mode.

L5 Agent-Native — 7 checks

Is your system built for AI agents? Checks for intent endpoints, agent session management, scoped tokens, and audit logging. Level 5 is verified externally — declared via a capabilities block in /.well-known/agent-card.json, OpenAPI x-consequence extensions, and similar signals — then confirmed with a live probe of the declared endpoints.

The --repo flag

By default, BotVisibility scans public HTTP endpoints — fetching well-known URLs, parsing headers, and validating API responses. All 58 checks across all five levels, including Level 5 Agent-Native, run against those external signals. The --repo flag supplements the external scan with local directory analysis, useful for finding implementations not yet exposed in public responses.

  • Works across any language — JavaScript, TypeScript, Python, Go, Java, Ruby, PHP, and more.
  • Supplements the external scan by pattern-matching source code for things like pagination logic, bulk endpoints, and agent session handling that haven’t been published yet.
  • Same 58 checks — the CLI runs the full checklist in your terminal or CI pipeline, not a different or reduced set.
# Point --repo at your project root
npx botvisibility mysite.com --repo ./

# Or a specific directory
npx botvisibility mysite.com --repo ./src

Scoring

BotVisibility uses a weighted cross-level algorithm — not strict sequential gates. Strong performance at higher levels can compensate for gaps at lower ones.

  • Level 1: 50%+ of L1 checks pass
  • Level 2: 50%+ of L1 AND L2 checks pass — or 35% L1 with 75% L2
  • Level 3: L2 achieved AND 50%+ L3 checks pass — or 35% L2 with 75% L3
  • Level 4: L3 achieved AND 50%+ L4 checks pass — or 35% L3 with 75% L4

This means a site with strong API design (L2/L3) but missing a few discovery files (L1) can still achieve a high score. The algorithm rewards depth, not just breadth.

CI/CD integration

Use --json output to integrate BotVisibility into your deployment pipeline. Fail builds when agent readiness drops below your threshold.

# .github/workflows/botvisibility.yml
name: BotVisibility Check
on: [push]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check BotVisibility
        run: |
          SCORE=$(npx botvisibility mysite.com --json | jq '.currentLevel')
          if [ "$SCORE" -lt 1 ]; then
            echo "BotVisibility score below Level 1"
            exit 1
          fi

Resources