C0028 cli-json-output¶
Rule: Every leaf command of a CLI has a machine-readable output flag.
| Code | C0028 (stable, never reused) |
| Id | cli-json-output |
| Category | cli |
| Source | spirit_level |
| Fix | by hand |
| Needs | cargo installed |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | an estimate: help does not say which commands print data, so it fires on every setup command until a project lists them in exempt |
| small-workspace | off | an estimate: help does not say which commands print data, so it fires on every setup command until a project lists them in exempt |
| medium | off | an estimate: help does not say which commands print data, so it fires on every setup command until a project lists them in exempt |
| big | off | an estimate: help does not say which commands print data, so it fires on every setup command until a project lists them in exempt |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
flags |
list of strings | ["--json", "--format"] |
flags that select a machine-readable output |
exempt |
list of strings | [] |
subcommand paths that print no data, words separated by spaces (* add; * one word, ** any) |
Why¶
A script that parses text output breaks when the wording changes. A machine-readable form (--json: one JSON value on stdout, JSONL for a stream) is an interface that stays. The guide asks for it on every command.
How to fix¶
Add --json (or --format json) to every command that prints data. A command that prints nothing a script reads (a setup step, completions) goes into the parameter exempt. The lint is an estimate: it assumes every leaf command prints data, which the help cannot tell. It is off in the shipped tiers; a project turns it on once it lists its exempt commands.
Configure¶
[lints.cli-json-output]
level = "deny"
flags = ["--json", "--format"]
exempt = []
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(cli-json-output) <reason> (waivers); the code works there too, as in [lints.C0028].