---
type: ultrabrief
brief_version: 1.0
slug: add-verbose-flag
task: Add a --verbose flag to the small-auth CLI parser
research_topics: 1
research_status: complete
brief_quality: ready
created: 2026-05-01
---

# Add `--verbose` flag to small-auth CLI

## Intent

The `small-auth` CLI parser has six commands (`login`, `logout`, `whoami`,
`token-refresh`, `users-list`, `users-create`) and currently emits only
final results — no progress, no timings, no internal step trace. Operators
debugging slow `token-refresh` calls or mis-routed `users-list` queries
have no signal between "started" and "finished".

We want a `--verbose` flag that, when passed, prints structured progress
lines to stderr without changing stdout output. Stdout stays the
machine-parseable contract; stderr becomes the human-readable trace.

## Goal

Add a single `--verbose` boolean flag, recognized by all six commands,
that emits one stderr line per internal step. No other behavioral
changes. The default (`--verbose` absent) produces output byte-identical
to today's CLI.

## Success Criteria

- `small-auth login --verbose alice` exits 0 and writes ≥ 3 stderr lines
  prefixed `[verbose]` covering: argument parse, credential lookup,
  session-token issue.
- `small-auth login alice` (no flag) writes exactly the same stdout as
  before this change — verified by golden-file diff against
  `tests/golden/login.stdout`.
- `--verbose` works in any position: `small-auth --verbose login alice`,
  `small-auth login --verbose alice`, `small-auth login alice --verbose`.
- `--verbose` short form is `-v`. `-vv` is **not** recognized — only one
  level. Document this in `--help`.
- All six commands accept the flag without rejection. Commands that have
  no internal steps to trace (`whoami`) still accept the flag silently.
- Existing 24 tests in `tests/` continue to pass. Two new tests added:
  one stdout-stability test, one stderr-content test for `login`.

## Out of scope

- Log levels beyond on/off (no `--debug`, `--trace`).
- Structured JSON logging — stderr stays plain text in this iteration.
- Logging configuration via env vars or config file.
- Any command other than the six listed.