gum

A tool for glamorous shell scripts

notable Go charmbracelet/gum

68% pass rate

1/8 principles met

Spec Coverage

How many of the spec's requirements were verified for this tool. See /coverage for the full matrix.

Level	Total	Verified	Unverified
MUST	28	19	9
SHOULD	21	13	8
MAY	10	10	0

Top Issues

FAIL Error messages include a hint or remediation phrase Fail-Fast, Actionable Errors stderr lacks a hint phrase. Looked for one of: try , use , expected , did you mean, see , run , for more, tip:, help:, hint:, suggestion:, available . Error messages must name what to do next, not just the symptom.
FAIL Each subcommand's `--help` ships at least one invocation example Progressive Help Discovery subcommands missing example invocations in their `--help`: choose, confirm, file, filter, format, input, join, pager, spin, style, table, write, log, version-check. Examples teach agents the call shape faster than option tables; use clap's `after_help` or a dedicated `Examples:` block.
FAIL Destructive subcommands require `--force` or `--yes` Safe Retries & Mutation Boundaries destructive subcommand(s) without `--force` or `--yes`: confirm, format. Irreversible operations must require explicit confirmation so they can't be invoked accidentally.

All Audits

P1: Non-Interactive by Default

PASS	Non-interactive by default
SKIP	Non-interactive gate flag advertised in --help	target satisfies P1 via alternative gate (help-on-bare or stdin-primary)
WARN	Flags advertise env-var bindings in --help	2 flag(s) found in --help but no `[env: NAME]` bindings advertised
PASS	Secret-bearing flags expose stdin or *-file companion
WARN	`--help` advertises default values for flags	no default-value annotations found in --help. SHOULD-tier — agents reading help text need to see what value a flag falls back to when omitted (`[default: <value>]` per clap convention).
PASS	Rich-TUI affordance for TTY contexts

P2: Structured, Parseable Output

WARN	Structured output support	--output/--format flag detected but could not validate JSON via safe probes (--help/--version override output flags in most CLIs)
SKIP	Structured-output CLI exposes its schema at runtime	no structured-output indicator (--output / --format / json / jsonl) in --help
WARN	--json / --jsonl short aliases for --output	no --json or --jsonl short alias found. Agents and pipelines benefit from short forms alongside the canonical `--output` enum.
WARN	`--raw` flag for pipe-safe unformatted output	no `--raw` flag advertised. MAY-tier — useful for pipelines that want to strip formatting before piping to other tools.
SKIP	`--output` advertises additional formats beyond text/json	no `--output` or `--format` flag advertised; vacuous skip for MAY-tier extra formats.
WARN	Bad invocation exits with structured usage-error code (2)	bad invocation exited with code 80. The 0/1/2/77/78 convention reserves code 2 for usage errors; using a different non-zero code (often 1) blurs the distinction between usage errors and general failure.
SKIP	Errors emit JSON envelope with `error`/`kind`/`message` under `--output json`	binary does not advertise `--output json` in --help; MUST applies only to CLIs that opt into the JSON contract.
SKIP	JSON success and error envelopes share their non-payload key set	binary does not advertise `--output json` in --help; envelope-consistency only applies to CLIs that opt into the JSON contract.

P3: Progressive Help Discovery

PASS	Help flag produces useful output
PASS	Version flag works (`--version` plus short alias)
PASS	Version flag works (`--version` plus short alias)
WARN	`examples` subcommand or `--examples` flag for curated usage patterns	no `examples` subcommand or `--examples` flag found. MAY-tier — a curated usage block keeps agents from hunting through long help text.
WARN	Short `-h` summary differs from `--help` long form	`-h` and `--help` produce byte-identical output. SHOULD-tier — clap renders the short summary on `-h` and the full description on `--help` when `long_about` is set; collapsing them gives agents no concise list-level grep target.
FAIL	Each subcommand's `--help` ships at least one invocation example	subcommands missing example invocations in their `--help`: choose, confirm, file, filter, format, input, join, pager, spin, style, table, write, log, version-check. Examples teach agents the call shape faster than option tables; use clap's `after_help` or a dedicated `Examples:` block.
WARN	Help text pairs human and `--output json` example invocations	no paired text + `--output json` example found within 5 lines in top-level or any subcommand `--help`. Pairing keeps agents from reverse-engineering the JSON invocation from the text one.

P4: Fail-Fast, Actionable Errors

PASS	Rejects invalid arguments
FAIL	Error messages include a hint or remediation phrase	stderr lacks a hint phrase. Looked for one of: try , use , expected , did you mean, see , run , for more, tip:, help:, hint:, suggestion:, available . Error messages must name what to do next, not just the symptom.
SKIP	`--output json` produces JSON-formatted errors	binary does not advertise `--output json` in --help; SHOULD applies only to CLIs that opt into the JSON contract.

P5: Safe Retries & Mutation Boundaries

FAIL	Destructive subcommands require `--force` or `--yes`	destructive subcommand(s) without `--force` or `--yes`: confirm, format. Irreversible operations must require explicit confirmation so they can't be invoked accidentally.
WARN	Read and write surfaces are both visible in subcommand list	write-pattern subcommand(s) present (confirm, format) but no read-pattern surface detected. If the CLI is write-only by design the MUST is satisfied vacuously; otherwise expose the read surface with agent-recognizable verbs (list/get/show/query/find/search).

P6: Composable, Predictable Command Structure

PASS	Handles SIGPIPE gracefully
WARN	Pager-using CLI ships --no-pager escape hatch	pager referenced in --help but no --no-pager escape hatch advertised
PASS	Respects NO_COLOR
WARN	Subcommand verbs follow community-standard names	0/14 subcommand(s) follow standard verb names. Non-standard: choose, confirm, file, filter, format, input, join, pager, spin, style, table, write, log, version-check. MAY-tier — community-standard verbs (get/list/create/update/delete) help agents predict subcommand behavior across CLIs.
WARN	`--color` flag for explicit color control	no `--color` flag advertised. MAY-tier — `auto\|always\|never` lets agents and pipelines override the TTY-based default.
WARN	Input-accepting commands read from stdin when no file is given	input-accepting subcommand present but `--help` does not mention stdin or `-` as a path placeholder. SHOULD-tier — agents piping data into the tool expect stdin to work when no file arg is provided.
PASS	Subcommand naming follows a consistent verb/noun convention
PASS	Operations are subcommands, not verb-shaped flags

P7: Bounded, High-Signal Responses

WARN	Quiet mode available	no --quiet/-q flag detected in --help output
PASS	`--verbose` flag for diagnostic escalation
SKIP	`--limit` / `--max-results` flag for list operations	no list-style subcommand detected (list/ls/search/query/find/show/get); vacuous skip for the list-only SHOULD.
SKIP	Cursor-based pagination flags for list traversal	no list-style subcommand detected; vacuous skip for the list-only MAY.
SKIP	`--timeout` flag for long-running operations	no long-running subcommand detected (serve/daemon/watch/tail/monitor/follow/run/start/stream); vacuous skip for the conditional SHOULD.
WARN	Help text advertises TTY-aware verbosity behavior	no TTY-aware language found in `--help`. MAY-tier — automatic verbosity reduction when stdout is piped or redirected lets agents skip the explicit `--quiet` flag. Behavioral probes cannot simulate a real TTY without a pty crate, so this audit relies on documented intent.

P8: Discoverable Through Agent Skill Bundles

PASS	Skill bundle has install path (`tool skill install [<host>]`)
PASS	`skill install --all` for multi-runtime install
PASS	`skill update` / `skill upgrade` for bundle refresh

Details

Version scored: 0.17.0
Audit date: 2026-06-01 17:36:38 UTC
Duration: 842ms
Platform: linux/x86_64
Mode: command
Anc build: 0.5.0
Install: brew install gum

Embed the badge

The badge floor is 70%; this scorecard is at 68% (2 points below). Once the score clears the floor, the embed snippet will appear here. The top issues above are the place to start.

Reproduce this scorecard for gum locally and inspect the failing audits:

anc audit --command gum --output json

Install anc first if you don't have it. Add --output json to get the same JSON shape committed under scorecards/.