arch-cli-contract

A CLI surface contract defines the external interface of a command-line tool, stabilizing the command tree, flags, arguments, and exit codes. You need one to ensure usage consistency and clear documentation between the tool and its users.

To document an existing command-line tool, use the Design or Document-existing mode to parse the tool and generate a Markdown contract. This output specifies the command tree, output formats, and error contracts automatically.

Yes, you can use the contract-first Design mode to define the CLI surface before implementation. This approach establishes a stable Markdown contract outlining expected commands, flags, and output formats early in development.

Yes, Python is required to run the scripts for parsing and formatting the CLI contract. The scripts automate the generation and maintenance of the Markdown documentation for your command-line tool.

The best way to scaffold a new command-line tool is using the Scaffold mode to generate the initial CLI contract. This establishes the foundational command tree, flag usage, and error contract before detailed development begins.

Automated CLI contract generation ensures comprehensive quality checks for flag usage and output separation, unlike manual documentation. It provides a stable, validated Markdown contract that stays consistent with the tool's actual surface.