Your CLI is an API, and agents are its users

What it does

CLIARE runs a released CLI binary through bounded black-box probes, records the runtime evidence, and infers a structured command surface. It emits a command-index.json catalog, issue ledgers, scorecards, and persona reports for maintainers, security reviewers, and agent harnesses. The goal is to replace hand-written help text and stale documentation with an evidence-backed contract that an autonomous agent can consume directly.

The interesting bit

The project treats CLI drift—where --help, docs, and the actual binary disagree—as an API compatibility bug rather than a documentation problem. By snapshotting filesystem state around each probe, it can even catch “safe” commands like --version or --help quietly writing cache files or credentials, which is exactly the kind of undocumented side effect that concerns security reviewers when autonomous agents are involved.

Key highlights

• Generates a command-index.json with command paths, flags, positionals, preconditions, output contracts, and confidence scores derived from runtime behavior, not static parsing.
• Detects side effects by snapshotting filesystem state, surfacing undocumented writes from seemingly read-only discovery commands.
• Outputs multiple persona-specific artifacts: maintainer fix queues, security side-effect reports, and harness-ready agent skills.
• Produces CI-friendly formats including SARIF and JUnit XML, framing agent-readiness gaps as release-gate failures.
• Supports configurable probing contexts (clean, authenticated, fixture-backed, host, CI) to measure behavior under different runtime conditions.

Caveats

• Deep traversal of large CLI surfaces is resource-intensive; the README shows a supabase example configured for 5,000 probes and concurrency of 8.
• Because it treats the CLI as a black box, inferred command shapes and side effects carry confidence scores rather than source-level certainty.
• Meaningful results depend on selecting the correct probing context; a mismatched context may miss commands or misreport preconditions.

Verdict

Worth a look if you maintain a CLI that autonomous agents might invoke, or if you build agent harnesses tired of token-burn from --help parsing loops. Skip it if your command-line tools are already simple, stable, and wrapped by proper programmatic APIs.