# Verbosity levels

- **Pattern:** `ab-000650` (`cli-quality.io-behavior.verbosity-levels`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000650
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000650)

## Why it matters

CI pipelines need quiet mode — `mytool build --quiet` so the log does not balloon with per-file output. Debugging sessions need verbose mode — `mytool build -v` to see which request failed or which config was loaded. A CLI that only outputs one noise level forces users into either information overload in CI or flying blind during incidents. Registering `--verbose` but never reading it in handlers is a worse sin: the flag looks supported, users trust it, and it silently does nothing.

## Severity rationale

Low because missing verbosity flags degrade debugging and CI output but do not affect core functionality.

## Remediation

Add `--verbose`/`-v` and `--quiet`/`-q` as global options in `src/cli/index.ts` and route all logging through a helper that honors them:

```ts
program.option('-v, --verbose').option('-q, --quiet')
function log(msg: string, { quiet, verbose }: Opts) {
  if (quiet) return
  console.error(msg)
}
function debug(msg: string, { verbose }: Opts) {
  if (verbose) console.error(`[debug] ${msg}`)
}
```

## Detection

- **ID:** `verbosity-levels`
- **Severity:** `low`
- **What to look for:** Count all logging and output statements. For each, check for `--quiet`/`-q` flag (suppress non-essential output) and `--verbose`/`-v` flag (show additional detail). Verify that `--quiet` actually suppresses output (only errors shown) and `--verbose` shows extra information (debug detail, timing, network requests). Check for stackable verbosity (`-vv`, `-vvv`) in CLIs with multiple verbosity levels.
- **Pass criteria:** At least `--verbose` is supported for increased output detail. `--quiet` for suppressed output is recommended. Verbosity flags actually change the output level (not just registered but ignored) — at least 2 verbosity levels (normal and verbose/debug) must be supported via --verbose or -v flag. Report even on pass: "X verbosity levels supported, --verbose and --quiet flags functional." Report: "X output statements found, Y respect verbosity level settings."
- **Fail criteria:** No `--verbose` or `--quiet` flags, or the flags are registered but have no effect on output.
- **Skip (N/A) when:** The CLI has minimal output by nature (e.g., a formatter that only outputs the formatted result). All checks skip when no CLI entry point is detected.
- **Detail on fail:** `"No --verbose or --quiet flags on any command"` or `"--verbose flag is registered but never checked in command handlers — has no effect"`
- **Remediation:** Verbosity control helps with debugging and CI integration:

  ```ts
  // commander — global verbosity options
  program
    .option('-v, --verbose', 'Show detailed output')
    .option('-q, --quiet', 'Suppress non-essential output')

  function log(message: string, opts: { verbose?: boolean, quiet?: boolean }) {
    if (opts.quiet) return
    console.error(message)  // messages to stderr
  }

  function debug(message: string, opts: { verbose?: boolean }) {
    if (opts.verbose) console.error(`[debug] ${message}`)
  }
  ```

---

Taxons: user-experience

HTML version: https://auditbuffet.com/patterns/ab-000650