CLI Principles
CLI Principles Section 8 Draft

Self-description

Source 08-self-description.md

Back to the spec index

  • <cli> -help: usage line first, then realistic examples, then parameters.
  • <cli> describe: machine-readable list of commands, parameters, input and output schemas, exit codes, each command’s class (query or mutation), and whether it is idempotent.
  • <cli> doc: prints full docs as Markdown.
  • <cli> skill: prints or installs agent skill files (SKILL.md). Generate skills and docs from the same source as the command definitions so they cannot drift. skill is encouraged for CLIs that agents use, and not required for every CLI.
  • Suggest, never run. An unknown command or parameter fails with invalid_input. The CLI never guesses and never runs a corrected command. The error may suggest the closest valid choice, in remediation or next, so a caller can decide.
  • Shell completions.