modiqo/cliare

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

What it solves

CLIARE（CLI Agent Readiness Evaluation）解决了命令行界面（CLI）在为人类设计与 AI 代理实际使用之间的差距。大多数 CLI 存在“漂移”——文档、帮助文本与实际运行时行为不一致——导致 AI 代理通过试错发现浪费 token 和延迟。它还帮助安全审查员识别看似只读的二进制文件中未文档化的副作用。

How it works

CLIARE 将 CLI 二进制视为黑盒，在受限控制下探测它，以衡量实际运行时行为。它不依赖静态文档，而是记录哪些命令存在、哪些标志安全、哪些输出可机器解析（JSON/YAML）。可以在不同上下文（干净、已认证或基于夹具）中运行，并生成一套完整的制品，最显著的是 command-index.json，作为代理程序使用的测量合约。

Who it’s for

  • CLI Maintainers：在发布新版本前识别并修复帮助覆盖、诊断信息和输出合约的缺口。
  • Security Reviewers：检测本应安全的命令中意外的文件写入或网络行为。
  • Agent Harness Builders：为代理提供预先测量的 CLI 表面映射，减少 token 消耗并提升可靠性。

Highlights

  • Evidence-Based Indexing：基于运行时证据生成 command-index.json，而非手写文档。
  • Black-Box Probing：对二进制进行测试，以推断命令形状并检测副作用。
  • Role-Specific Reporting：为维护者（修复队列）、安全（副作用报告）和 harness（路由答案）提供定制报告。
  • CI Integration：包含 GitHub Action，实现就绪度审计自动化并根据评分卡设置发布门槛。
  • Surface Querying：允许 harness 通过 cliare surface query 将任务意图解析为具体、已就绪的命令。