modiqo/cliare

CLI agent-readiness measurement, command-shape inference, and CI scorecards

What it solves

CLIARE (CLI Agent Readiness Evaluation) addresses the gap between how command-line interfaces (CLIs) are designed for humans and how they are used by AI agents. Most CLIs suffer from "drift"—where documentation, help text, and actual runtime behavior differ—leading to AI agents wasting tokens and latency through trial-and-error discovery. It also helps security reviewers identify undocumented side effects in binaries that appear to be read-only.

How it works

CLIARE treats the CLI binary as a black box and probes it under bounded controls to measure its actual runtime behavior. Instead of relying on static documentation, it records evidence of which commands exist, which flags are safe, and which outputs are machine-parseable (JSON/YAML). It can run in various contexts (clean, authenticated, or fixture-backed) and generates a comprehensive set of artifacts, most notably a command-index.json that serves as a measured contract for agent harnesses.

Who it’s for

  • CLI Maintainers: To identify and fix gaps in help coverage, diagnostics, and output contracts before shipping releases.
  • Security Reviewers: To detect unexpected filesystem writes or network behavior in commands that should be safe.
  • Agent Harness Builders: To provide agents with a pre-measured map of the CLI surface to reduce token burn and improve reliability.

Highlights

  • Evidence-Based Indexing: Generates a command-index.json based on runtime evidence rather than hand-written docs.
  • Black-Box Probing: Exercises the binary to infer command shapes and detect side effects.
  • Role-Specific Reporting: Provides tailored reports for maintainers (fix queues), security (side-effect packets), and harnesses (routing answers).
  • CI Integration: Includes a GitHub Action to automate readiness audits and set release gates based on scorecards.
  • Surface Querying: Allows harnesses to resolve task intents to specific, ready commands via cliare surface query.