# CLI Contract

> Check a platform's command-line interface against the design that serves a human at a terminal, a CI script and a
> coding agent alike. List the commands, exit codes and environment variables; the browser reads the grammar, checks
> --json coverage, severe-action guards, idempotency, wait and dry-run flags, secrets accepted as flags, the
> environment prefix and the exit codes against the eight caller actions, scores the five gates, and ranks the command
> layer and the telemetry posture. Metered runs write the CLI design spec, and the release plan. Built on the
> SkillSafe skill @samber/cli-interface-design, from samber/developer-platform-skills (MIT), by Samuel Berthe.

https://cli-contract.skillsafe.ai/

## What is free
- Grammar: one order (noun verb or verb noun), no near-synonym verbs, no API-shaped names, a raw api escape hatch.
- The contract: --json on every command that returns data or mutates state, streams on --format ndjson, lists in one envelope with a bounded --limit and an explicit --all, one environment prefix, one documented resolution order, unknown flags rejected.
- Output and exit codes: errors as one --json document, colour and pagers only on a terminal, the exit codes classified as success, failure, usage, authentication, not found, safe to rerun, outcome unknown and partial failure (nothing above 125, no BSD sysexits), bounded waits with --no-wait and detach, --idempotency-key on creates.
- Safety: no prompt, pager or update check reachable in CI, --no-input, severe actions confirmed by name or count in the curated commands and the escape hatch alike, --dry-run, typo suggestions never auto-run.
- Auth: no secret only as a flag, no print-the-token command, credentials in the OS store, test mode shown.
- Agents and release: a self-description command, help examples and completion, telemetry never switched on in a minor release, update checks at most daily on a terminal.
- The five gates, the rankings (command layer, telemetry), an exit-code table, a severity table and a self-description document, and exports: the checks (.csv), everything (.json).

## The metered lanes
Two tasks on gpt-terra, metered per run, routed by `task`. Input string fields: `task` (design or release), `platform`, `cli`, `carry` (release only: the design's decisions) and `facts`.
- `design` replies with `summary`, `layers`, `grammar`, `commands` (each with replaces, json, severity, confirm and flags to add), `exit_codes` (the eight classes), `config_order`, `env_prefix`, `auth`, `frozen` and `caveats`.
- `release` replies with `summary`, `versioning`, `deprecation`, `telemetry`, `updates`, `gates` (the five, each with a test), `agents`, `migration`, `trends` and `caveats`.
The page holds every reply to its own facts: the ranked rungs, one grammar without near-synonyms, every listed command covered with --json where data flows and a name or count guard where it is severe, the eight exit classes once each, the config order, one prefix, the auth contexts; at least 12 months or 2 releases of deprecation, DO_NOT_TRACK, daily terminal-only update checks, the five gates and a migration for a shipped CLI.

## Links
- API tutorial: https://cli-contract.skillsafe.ai/api.html
- Source skill: https://skillsafe.ai/skill/@samber/cli-interface-design