CLIARE: Measuring a Released CLI's Agent Readiness as a Black Box
CLI agent-readiness measurement, command-shape inference, and CI scorecards
At a glance
- What is it?
- CLIARE is a Rust tool that probes a released CLI binary under bounded controls and emits command indexes, issue ledgers, scorecards and CI artifacts. It is useful when an agent harness needs runtime evidence about a CLI surface, and unnecessary when the surface is small and stable.
- Who is it for?
- Adopt CLIARE if you ship a CLI whose command surface drifts between releases and you want a measured contract for the agent harnesses that consume it, or if you review binaries for undocumented side effects. Skip it if your CLI is a handful of stable commands, since the probe matrix and the evidence directory are overhead you will not read.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 45 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The drift problem CLIARE measures instead of documents
The README states the premise directly: when a CLI evolves quickly, the docs, --help output, and the released binary can start telling different stories. A human reading help text can absorb that mismatch and route around it. An agent harness cannot, because it has no prior model of the CLI. It discovers the surface by trying commands, hitting a missing operand, backing up, and trying again. The README calls this loop token burn, and that is the problem CLIARE targets.
The intended audience is narrow and specific. CLI maintainers who want command-shape drift caught before a release. Security reviewers who need to know whether a command that looks read-only actually writes files. Agent harness authors who currently hardcode assumptions about a CLI they do not control. The project describes itself as being like OpenAPI/Swagger for CLIs, with the qualification that the description is generated from runtime evidence rather than hand-written docs. That qualification is the whole design argument: a hand-written spec can be as stale as the help text it replaces.
Black-box probing, evidence capture, and what the index actually contains
CLIARE does not parse your source or read your argument parser's schema. According to the README, it exercises the released binary as a black box, probing runtime behavior under bounded controls, recording evidence, inferring the command surface, and detecting side effects. The output set listed is broad: command indexes, issue ledgers, scorecards, one-command summaries, persona reports, CI artifacts, and agent skills.
The command index is the artifact that matters most for harness integration. The README says it describes command paths, flags, operands, preconditions, output contracts, confidence, suitability, and evidence references. Confidence and evidence references are the interesting fields. A hand-written spec asserts; an index that carries confidence per entry and a pointer back to the probe that produced it lets a harness decide how much to trust a given command path. The persona reports split the same underlying measurements for different readers: maintainer, harness, and security, each with its own report command and output format.
The security angle is the least obvious part. The README states that CLIARE snapshots filesystem state around each probe and reports persistent side effects from commands that look safe, naming help, version, invalid flag, and output-mode probes as examples. It also separates expected auth, host, network, daemon, and fixture behavior from surprises. That distinction is doing real work: a CLI that writes to a cache directory on --version is a finding, while a CLI that writes credentials when you explicitly authenticate is expected behavior, and a tool that cannot tell those apart produces noise.
Install, measure, and the flags that define the probe context
The README gives cargo install cliare as the installation path, followed by cliare metadata --format json. Measurement starts with cliare measure, and the flags shown in the examples define the context the probes run in.
The simplest invocation in the README is cliare measure mycli --out .cliare/mycli --profile standard --refresh. The deeper example adds the context controls: cliare measure mycli --out .cliare/mycli --context authenticated --auth-state present --execution-mode host --profile deep --refresh. The README lists the available contexts as clean, repository, authenticated, host, fixture-backed, and CI. Those names describe the environment the binary is probed in, which is why --auth-state and --execution-mode appear alongside --context rather than being inferred.
Downstream commands read the same output directory. cliare summary --out .cliare/mycli produces the one-command summary and accepts --format json. cliare describe .cliare/mycli --write generates the description. cliare report maintainer, cliare report harness, and cliare report security each take --out and --format markdown, with the harness report also accepting --write. cliare issues list --out .cliare/mycli --format markdown or --format human produces the issue ledger. cliare playbook maintainer --target mycli and cliare playbook harness --target mycli generate the persona playbooks.
The files a harness loads are named explicitly in the README: .cliare/mycli/command-index.json, .cliare/mycli/AGENT_SKILL.md, and .cliare/mycli/persona-harness.json. That is the integration surface. Anything consuming CLIARE output should be reading those paths, not scraping the markdown reports.
Probing a real binary is not free, and the context you choose decides the result
The honest limitation is in the method itself. CLIARE runs the binary. A deep profile against a CLI that talks to a network service, starts a daemon, or touches a credential store will do those things during measurement, because that is what the tool is designed to observe. The README's answer is the context and auth-state flags, which is a reasonable answer but also puts the burden on you: pick --context authenticated without a real auth state present and the probes will record precondition blockers that say more about your test environment than about the CLI. Pick --execution-mode host when the CLI expects a container and you get a different set of failures.
There is a second, quieter limitation. Inferred command shape is inference. The README's own framing, generated from runtime evidence rather than hand-written docs, means the index reflects what the probes reached, not what the CLI supports. A command gated behind a flag combination the probe matrix never tries will be absent or low-confidence rather than wrong, and absent entries are easy to misread as unsupported. The confidence field exists for this reason, and a harness that ignores it is using the index badly.
Finally, CLIARE is at v0.1.9, released 2026-07-02, with v0.1.8 the same day and v0.1.7 about two weeks earlier. Three patch releases in that window is a normal cadence for a young tool, but it also means the output format and the flag set are still moving. Pin the version you build against in CI rather than tracking latest.
Where CLIARE sits next to schema-first tooling
The natural comparison is a schema-first approach: write an OpenAPI-style description of the CLI by hand, or generate one from your argument parser's definitions, and hand that to the harness. Tools in that family derive the contract from source, which means the contract is complete by construction and cheap to regenerate on every build.
The difference in approach is the source of truth. A generated-from-source spec knows every command and flag the parser defines, including ones that are broken at runtime, gated behind a feature flag, or unreachable in the shipped binary. CLIARE knows only what it reached, but it knows it from the artifact you actually ship, which is the same artifact the agent will run. If your failure mode is a flag that exists in the parser but panics, or a discovery command that writes to disk, source-derived tooling will not surface it and CLIARE will.
The reverse trade holds too. If your CLI is generated from a declarative definition and the runtime faithfully matches it, CLIARE's probe matrix is measuring something you already know, and the cost is a slower CI job plus an evidence directory nobody reads.
Release gates, upgrade cost, and the Apache-2.0 terms
The README frames the maintainer workflow as a release-time fix queue: missing help, confusing diagnostics, parseable-output gaps, unsafe discovery side effects, precondition blockers, and command-shape drift. It also lists release gates for help coverage, diagnostics, parseable output, and unsafe discovery behavior as a benefit. That is the CI shape the project is aiming at, and the scorecards and CI artifacts are the mechanism.
The maintenance cost falls in two places. First, the probe run itself: a deep profile against a CLI with network or daemon dependencies is a slow job, and it needs an environment where those dependencies exist. Second, the index: once a harness loads .cliare/mycli/command-index.json, every release that changes the command surface changes that file, and something downstream has to notice. CLIARE produces the artifact; it does not describe a consumer-side diffing process in the material available here.
Licensing is Apache-2.0, which permits commercial and closed-source use and includes an explicit patent grant. The repository carries no separate licence note in the supplied material, so the standard Apache-2.0 terms apply as written. That is a factual statement about the licence identifier, not a legal opinion; if you are redistributing a modified CLIARE or bundling it into a product, read the NOTICE and attribution requirements yourself.
Skills teach intent, indexes map the surface
One section of the README makes a distinction worth repeating because it is the most useful design idea in the project. Skills and command indexes are not substitutes. A skill teaches intent, workflow, and policy. A command index tells the harness what the CLI actually supports right now. CLIARE generates both, and the README's position is that agents need both: instruction for judgment, evidence for navigation.
That framing also explains why CLIARE does not try to be an agent framework. It produces files. The harness decides how to load them, when to trust a low-confidence entry, and what to do when a precondition is not met. The tool's job ends at the evidence.
Whether that division holds up depends on the confidence calibration, which is the thing to check first in practice. If entries marked high confidence in command-index.json turn out to be commands that fail under the harness's real conditions, the index is worse than no index, because the harness will trust it. Run the measure command against the binary in the environment the agent actually runs in, not a clean container, and compare the recorded preconditions against what you know.
Editorial conclusion
Adopt CLIARE if you ship a CLI whose command surface drifts between releases and you want a measured contract for the agent harnesses that consume it, or if you review binaries for undocumented side effects. Skip it if your CLI is a handful of stable commands, since the probe matrix and the evidence directory are overhead you will not read. Before committing, run cliare measure against your real binary with --context and --auth-state set to match your production environment, then open .cliare/<target>/command-index.json and check whether the preconditions and output contracts it records match what you know to be true. If they do not, the probe context is wrong, not the tool.
Community notes