STD-008: CLI Quality Standard

Every command written in documentation, runbooks, or AI-generated output MUST follow the verification pattern and meet quality criteria for idempotency, precision, and teachability.

Principles

  1. Verify-before, change, verify-after. The atomic unit of change is three commands, not one. See STD-005 for the full change control standard.

  2. Idempotent where possible. A command run twice MUST produce the same result as running it once.

  3. Teach the tool’s affordance. When presenting a command, explain WHY this tool is the right choice — not just the syntax.

  4. Placeholders have examples. Every <placeholder> MUST be followed by a concrete example showing real values.

Requirements

  1. Commands in documentation MUST follow the verify-change-verify pattern (STD-005).

  2. Commands SHOULD be idempotent. Use grep -q guards, test -f conditionals, and systemctl is-active checks.

  3. Every <placeholder> in a command MUST be followed by a concrete example with real values.

  4. Separate commands when each warrants individual verification. Group ONLY when they form a single indivisible logical unit.

  5. Use git -C <path> instead of cd && git. Parallel pushes with & + wait.

  6. Prefer awk for field extraction over cut. Prefer awk pattern ranges over grep | head/tail pipelines. Reduce pipe stages where a single tool suffices.

  7. Avoid useless use of cat (cat file | grep → grep pattern file).

  8. Process substitution (diff <(cmd1) <(cmd2)) SHOULD replace temp files for comparisons.

CLI Coaching Targets

When a user or document uses a basic approach, the preferred alternative SHOULD be demonstrated:

Basic Preferred

grep pattern file | head -5

awk '/pattern/ && ++c⇐5' file

cat file | grep

grep pattern file

cd dir && git status

git -C dir status

head -n 20 file | tail -n 5

awk 'NR>=16 && NR⇐20' file

temp files for comparison

diff <(cmd1) <(cmd2)

cut -d: -f1

awk -F: '{print $1}'

Compliance

Check Method Pass Criterion

Placeholders have examples

Every <placeholder> is followed by a # Example: comment or inline example

No orphaned placeholders

Idempotent where possible

Commands use conditional guards

Re-execution is safe

No useless cat

grep -r 'cat .* |' pages/ runbooks/

Zero unnecessary pipes from cat

Verify-change-verify present

Configuration change blocks include before/after verification

Three-step pattern visible

Exceptions

Interactive commands (bluetoothctl, nmtui, fdisk) cannot follow verify-change-verify within the interactive session. Document the before-state capture and after-state verification as separate commands outside the interactive block.

Related