Skip to content

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].