modiqo/cliare

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

What it solves

CLIARE (CLI Agent Readiness Evaluation)는 명령줄 인터페이스(CLI)가 인간을 위해 설계된 방식과 AI 에이전트가 실제로 사용하는 방식 사이의 격차를 해결합니다. 대부분의 CLI는 문서, 도움말 텍스트, 실제 런타임 동작이 서로 다르게 나타나는 "드리프트" 현상이 있어 AI 에이전트가 시도와 오류를 통해 토큰과 지연 시간을 낭비하게 합니다. 또한 읽기 전용으로 보이는 바이너리에서 문서화되지 않은 부작용을 보안 검토자가 식별하는 데도 도움이 됩니다.

How it works

CLIARE는 CLI 바이너리를 블랙박스로 취급하고 제한된 제어 하에 프로빙하여 실제 런타임 동작을 측정합니다. 정적 문서에 의존하지 않고 어떤 명령이 존재하고, 어떤 플래그가 안전하며, 어떤 출력이 머신 파싱 가능(JSON/YAML)한지를 증거로 기록합니다. 클린, 인증된, 혹은 픽스처 기반 등 다양한 컨텍스트에서 실행될 수 있으며, 포괄적인 아티팩트 세트를 생성합니다. 그 중 가장 눈에 띄는 것은 command-index.json이며, 이는 에이전트 하니스가 사용할 측정된 계약 역할을 합니다.

Who it’s for

  • CLI Maintainers: 릴리즈 전에 도움말 커버리지, 진단, 출력 계약의 격차를 식별하고 수정합니다.
  • Security Reviewers: 안전해야 할 명령에서 예상치 못한 파일 쓰기나 네트워크 동작을 감지합니다.
  • Agent Harness Builders: 에이전트에게 사전 측정된 CLI 표면 맵을 제공해 토큰 소모를 줄이고 신뢰성을 향상시킵니다.

Highlights

  • Evidence-Based Indexing: 수동 문서가 아니라 런타임 증거를 기반으로 command-index.json을 생성합니다.
  • Black-Box Probing: 바이너리를 실행해 명령 형태를 추론하고 부작용을 탐지합니다.
  • Role-Specific Reporting: 유지보수자(수정 큐), 보안(부작용 패킷), 하니스(라우팅 답변)를 위한 맞춤형 보고서를 제공합니다.
  • CI Integration: GitHub Action이 포함되어 준비도 감사를 자동화하고 스코어카드 기반 릴리즈 게이트를 설정합니다.
  • Surface Querying: 하니스가 cliare surface query를 통해 작업 의도를 구체적이고 준비된 명령으로 해결할 수 있게 합니다.