Half your users don't have eyes

Description and use

CLI tools often emit only human‑readable text, breaking scripts and CI. By adding a --output json flag and wrapping results in a stable JSON envelope, programs get a reliable contract while human output can be freely improved.

Problem

CLI tools often output only human‑readable text, breaking scripts, CI pipelines, and automation that rely on parsing that output.

Outcome

Automated consumers no longer break when human output changes; scripts can reliably check status and extract data. Human output becomes more readable and maintainable.

Workflow

• 1. Add a --output flag to every command using the framework.
• 2. When --output json is requested, serialize the command result into a Response envelope.
• 3. Scripts and CI jobs call the command with --output json and parse the JSON payload.
• 4. Human users run the command without the flag to see the friendly text.
• 5. Maintain the envelope shape across all commands to keep the contract stable.

Evidence

The consumer-side payoff is the whole point. A script can check .status without ever touching .data.

Source

Machines get a stable, explicit, learn-it-once contract; humans get output that's now free to be properly readable.

Source