AIE-CLI-Scanner

Check if your CLI tool is AI-ready — 7-dimension scoring in one command.

Scan GitHub repos, local projects, or installed CLI commands and get a compatibility score, token heatmap, badge, and actionable fix suggestions.

Quick Start

# Scan an installed CLI command
npx aie-scan git
npx aie-scan gh
npx aie-scan node

# Scan a GitHub project
npx aie-scan https://github.com/stripe/stripe-cli

# Scan a local project
npx aie-scan ./my-cli-project

# JSON output
npx aie-scan gh --json

# Markdown report
npx aie-scan gh --markdown

# Generate Badge SVG
npx aie-scan gh --badge

# Detailed fix suggestions
npx aie-scan gh --fix

Three Scan Modes

| Mode | Input | What it does | |------|-------|--------------| | Command | aie-scan gh | Runs --help, --version, analyzes binary permissions | | GitHub | aie-scan https://github.com/... | Shallow clones and scans source code | | Local | aie-scan ./path | Scans a local project directory |

7-Dimension Scoring

| Dimension | Weight | What it checks | |-----------|--------|----------------| | AI Readability | 15% | Structured output, non-interactive mode, help parseability | | Security | 15% | Binary permissions, injection risks, hardcoded secrets, telemetry | | Token Efficiency | 15% | Token consumption of help output, output trimming support | | Documentation | 15% | Help text quality, usage examples, version info, AI-readiness | | Functional Completeness | 15% | CLI installable, --help works, commands execute | | Dependency Health | 10% | CVE scan, outdated deps, license compatibility | | Community Health | 15% | Stars, recent commits, contributor count |

MVP (v0.1.0) implements 4 of 7 dimensions: AI Readability, Security, Token Efficiency, Documentation.

Grades

• Gold (90-100): Top-tier AI compatibility
• Silver (70-89): Good AI compatibility, minor improvements needed
• Bronze (50-69): Basic compatibility, several improvements recommended
• Risk (25-49): Security or usability concerns
• Fail (<25): Major issues, not suitable for AI agent use

Example Output

  ┌────────────────────────────────────────────────────────────┐
  │  AIE Score: 67/100  Bronze ★
  │  git (other)
  ├────────────────────────────────────────────────────────────┤
  │  ⚠️  AI 可读性 (AI Readability)      63/100  [█████████████░░░░░░░]
  │  ✅  安全性 (Security)               79/100  [████████████████░░░░]
  │  ⚠️  Token 效率 (Token Efficiency)  64/100  [█████████████░░░░░░░]
  │  ⚠️  文档质量 (Documentation)        62/100  [████████████░░░░░░░░]
  ├────────────────────────────────────────────────────────────┤
  │  Token Heatmap:
  │    --help (full)          █████░░░░░░░░░░░░░░░░░░░░   587 tok ⚠️
  │    clone                  ███░░░░░░░░░░░░░░░░░░░░░░   346 tok ⚠️
  │    init                   ███░░░░░░░░░░░░░░░░░░░░░░   335 tok ⚠️
  │    add                    ███░░░░░░░░░░░░░░░░░░░░░░   304 tok ⚠️
  │    diff                   ██░░░░░░░░░░░░░░░░░░░░░░░   221 tok ✅
  │    log                    ██░░░░░░░░░░░░░░░░░░░░░░░   197 tok ✅
  │    status                 ██░░░░░░░░░░░░░░░░░░░░░░░   181 tok ✅
  ├────────────────────────────────────────────────────────────┤
  │  🔧 Recommendations: 7 items
  │    🟡 [AI Readability] Non-Interactive Mode Support (2h)
  │    🟡 [Security] Dangerous Flags Detection (2h)
  │    🟡 [Documentation] Usage Examples in Help (2h)
  ├────────────────────────────────────────────────────────────┤
  │  🏷️  Badge: https://aie.dev/badge/git.svg
  └────────────────────────────────────────────────────────────┘

Token Heatmap (Unique Feature)

Token consumption per command — unique to AIE Scanner, no competitor covers this. Works across all help text formats:

  --help (full)          █████░░░░░░░░░░░░░░░░░░░░   587 tok ⚠️
  clone                  ███░░░░░░░░░░░░░░░░░░░░░░   346 tok ⚠️
  init                   ███░░░░░░░░░░░░░░░░░░░░░░   335 tok ⚠️
  diff                   ██░░░░░░░░░░░░░░░░░░░░░░░   221 tok ✅

Markdown Report

Use --markdown for a structured report with tables:

npx aie-scan gh --markdown --output report.md

Generates tables for dimensions, token heatmap, check details, and recommendations.

Badge

Add to your README:

[![AIE Score](https://api.aie.dev/v1/badge/your-cli.svg)](https://aie.dev/tools/your-cli)

CLI Options

aie-scan <input> [options]

Arguments:
  input                 GitHub URL, local path, or installed CLI command name

Options:
  --json                Output as JSON
  --markdown            Output as Markdown
  --output <path>       Write output to file
  --badge               Generate Badge SVG file
  --fix                 Show detailed fix suggestions
  --verbose             Verbose logging
  --no-color            Disable colored output
  --version             Show version
  --help                Show help

Development

pnpm install
pnpm build          # Build with tsup
pnpm test           # Run tests with Vitest
pnpm test:coverage  # Test coverage report
pnpm typecheck      # TypeScript type checking
pnpm dev            # Watch mode

Architecture

src/
├── cli.ts                    # Commander CLI definition
├── scanner.ts                # Scan orchestrator
├── types.ts                  # Core type definitions
├── project-resolver.ts       # Input resolution (GitHub/local/command)
├── language-detector.ts      # Language detection
├── checkers/
│   ├── index.ts              # Checker interface & registry
│   ├── ai-readability.ts     # AIR-001~007 checks
│   ├── security.ts           # SEC-001~007 (project/command mode)
│   ├── token-efficiency.ts   # TOK-001~005 + heatmap
│   └── documentation.ts      # DOC-001~007 (project/command mode)
├── reporters/
│   ├── terminal-reporter.ts  # ASCII box-drawing report
│   ├── json-reporter.ts      # JSON output
│   ├── markdown-reporter.ts  # Markdown tables report
│   └── badge-generator.ts    # SVG badge generation
└── utils/
    ├── tokenizer.ts          # js-tiktoken wrapper
    ├── help-parser.ts        # Multi-format help output parser
    ├── file-reader.ts        # Project file collection
    └── score-calculator.ts   # Severity-weighted scoring engine

Score Summary (Sample Scans)

| CLI | Score | Grade | Security | Docs | Heatmap Entries | |-----|-------|-------|----------|------|-----------------| | python3 | 81/100 | Silver | 100 | 81 | 2 | | node | 80/100 | Silver | 69 | 100 | 18 | | git | 67/100 | Bronze | 79 | 62 | 21 | | gh | 67/100 | Bronze | 100 | 62 | 11 | | pnpm | 64/100 | Bronze | 100 | 62 | 13 |

License

MIT