CLISpec

CLISpec compiles CLI help output into structured, agent-ready specifications.

It discovers command trees, parses options/arguments, classifies risk, and renders output for humans and tooling.

Features

• Recursive CLI discovery with help-only execution.
• Structured CLISpec v1 JSON output.
• Markdown and YAML rendering.
• Diff mode with breaking-change detection.
• Validation command for schema checks.
• Inspect command for parser diagnostics.
• Parse confidence scoring and warning signals.
• Framework-aware parsing strategy (generic, Cobra, Click, Clap).
• Optional LLM enrichment with local cache.
• Provider support: Mock, OpenRouter, OpenAI, Anthropic.
• OpenAI and Anthropic providers use official SDK clients.

Install

From source

npm install
npm run build
node dist/cli/index.js --help

Local binary link

npm link
clispec --help

CLI Usage

clispec <command> [options]

Commands:

• analyze <cli-name-or-path>
• diff <old-spec> <new-spec>
• validate <spec-file>
• render <spec-file>
• inspect <cli> [command ...]
• init

Examples

Analyze a CLI and write json/markdown:

clispec analyze node --format all --output ./tmp/node-spec --risk

Analyze with LLM enrichment (mock provider):

clispec analyze node --format json --llm --provider mock --llm-cache-dir ./.clispec-cache/llm

Analyze with OpenRouter enrichment:

export OPENROUTER_API_KEY="your-key"
clispec analyze node --format json --llm --provider openrouter --model openai/gpt-4o-mini

Analyze with API key via flag:

clispec analyze node --format json --llm --provider openrouter --api-key "your-key"

Analyze with API keys via config:

clispec analyze node --llm --provider openai --config ./clispec.config.json

Example clispec.config.json:

{
  "llm": {
    "enable": false,
    "provider": "openrouter",
    "model": "openai/gpt-4o-mini",
    "cacheDir": ".clispec-cache/llm",
    "apiKeys": {
      "openrouter": "",
      "openai": "",
      "anthropic": ""
    }
  },
  "risk": {
    "enable": true,
    "strict": false
  }
}

Analyze with OpenAI enrichment:

export OPENAI_API_KEY="your-key"
clispec analyze node --format json --llm --provider openai --model gpt-4o-mini

Analyze with Anthropic enrichment:

export ANTHROPIC_API_KEY="your-key"
clispec analyze node --format json --llm --provider anthropic --model claude-sonnet-4-0

Validate a generated spec:

clispec validate ./tmp/node-spec.json

Diff two specs and fail CI on breaking changes:

clispec diff ./tmp/old.json ./tmp/new.json --ci

Render JSON spec to YAML:

clispec render ./tmp/node-spec.json --format yaml --output ./tmp/node-spec.yaml

Inspect parser output:

clispec inspect node --raw

CI Gates

analyze supports policy gating:

• --ci
• --ci-min-confidence <0..1>
• --ci-max-warnings <n>

LLM options:

• --llm
• --provider <mock|openrouter|openai|anthropic>
• --model <provider-model-id>
• --api-key <key>
• --openrouter-api-key <key>
• --openai-api-key <key>
• --anthropic-api-key <key>
• --llm-cache-dir <path>
• --llm-strict
• --config <path>

API key source precedence for selected provider:

1. Provider-specific flag: --openrouter-api-key / --openai-api-key / --anthropic-api-key
2. Generic flag: --api-key
3. Config provider key: llm.apiKeys.<provider> (or llm.openrouterApiKey / llm.openaiApiKey / llm.anthropicApiKey)
4. Config generic key: llm.apiKey
5. Environment variable: OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY

Security note:

• CLISpec does not print API key values in verbose logs.
• For CI usage, prefer environment variables over CLI flags to avoid exposing secrets in shell history/process listings.
• Enrichment outputs are normalized before use (trimmed, deduplicated, bounded length).
• Use --llm-strict to fail fast when provider output is malformed.

Exit codes:

• 0 success
• 1 policy/breaking failure
• 2 usage/runtime failure

Development

npm run check
npm run build
npm run test

Known Limitations

• Parser extraction is heuristic; unusual/custom help layouts can still require manual review.
• Multi-line and mixed value syntaxes are supported, but deeply nested formatting variants may not be fully normalized.
• LLM enrichment is optional and should be treated as assistive metadata, not an authoritative source of command safety.

Changelog and Versioning

Release notes are tracked in CHANGELOG.md.
Versioning follows Semantic Versioning (MAJOR.MINOR.PATCH).

Release process checklist is documented in RELEASE.md.

License

MIT - see LICENSE.