modiqo/cliare

What it solves

CLIARE (CLI Agent Readiness Evaluation) solves the problem of "CLI drift," where a command-line interface's actual runtime behavior differs from its documentation or help text. This drift causes AI agents to waste tokens and latency by repeatedly guessing commands and flags through trial and error. It also helps security reviewers identify undocumented side effects (like unexpected file writes) that occur during seemingly safe discovery commands.

How it works

CLIARE treats a CLI binary as a black box and probes it under bounded controls. Instead of relying on static documentation, it exercises the binary in various contexts (clean, authenticated, or fixture-backed) to record evidence of what commands actually exist, which flags are safe, and whether outputs are machine-parseable (JSON/YAML). It then generates a command index and a set of reports (scorecards, issue ledgers, and persona-specific packets) that map the real surface of the CLI.

Who it’s for

• CLI Maintainers: To identify gaps in help coverage, diagnostics, and output contracts to make their tools agent-friendly.
• Security Reviewers: To detect undocumented runtime behavior and persistent side effects in binaries before exposing them to autonomous agents.
• Agent Harness Builders: To obtain an evidence-backed command index that allows agents to route to the correct command without rediscovering syntax via trial and error.

Highlights

• Evidence-Based Mapping: Generates a command-index.json based on runtime evidence rather than hand-written docs.
• Black-Box Probing: Measures the binary in isolated or host-specific contexts to detect side effects.
• Agent-Ready Artifacts: Produces AGENT_SKILL.md and persona reports to guide agent behavior.
• Surface Querying: Provides tools for harnesses to query intent-to-command routing answers.
• CI Integration: Includes a GitHub Action to automate readiness audits and create release gates.