cli-logging-ux

CLI Logging UX expert persona

CLI Logging & Developer Experience

Decision framework

Apply these three tests to every piece of user-facing output. If a message fails any test, redesign it.

1. The "So What?" Test

Every warning must answer: what should the user do about this?

# Fails — not actionable, user can't do anything
Sub-skill 'my-skill' from 'my-package' overwrites existing skill

# Passes — tells the user exactly what to do
Skipping my-skill — local file exists (not managed by APM). Use 'apm install --force' to overwrite.

If the user can't act on it, it's not a warning — it's noise. Demote to --verbose or remove.

2. The Traffic Light Rule

Use color semantics consistently. Never use a warning color for an informational state.

3. The Newspaper Test

Can the user scan output like headlines? Top-level = what happened. Details = drill down.

# Bad — warnings break the visual flow between status and summary
[checkmark] package-name
[warning] something happened
[warning] something else happened
  [tree] 3 skill(s) integrated

# Good — clean tree, diagnostics at the end
[checkmark] package-name
  [tree] 3 skill(s) integrated

── Diagnostics ──
  [warning] 2 skills replaced by a different package (last installed wins)
    Run with --verbose to see details

Inline output vs deferred diagnostics

Use inline output for:

• Success confirmations (_rich_success)
• Progress updates (_rich_info with indented └─ prefix)
• Errors that halt the current operation (_rich_error)

Use DiagnosticCollector for:

• Warnings that apply across multiple packages (collisions, overwrites)
• Issues the user should know about but that don't stop the operation
• Anything that would repeat N times in a loop

DiagnosticCollector categories: skip() for collisions, overwrite() for cross-package replacements, warn() for general warnings, error() for failures.

Console helper conventions

Always use the helpers from apm_cli.utils.console — never raw print() or bare click.echo().

Emojis are banned. Never use emoji characters anywhere in CLI output — not in messages, symbols, help text, or status indicators. Use ASCII text symbols exclusively via STATUS_SYMBOLS.

Use STATUS_SYMBOLS dict with symbol= parameter for consistent ASCII prefixes:

Output structure pattern

Follow this visual hierarchy for multi-package operations:

Content-awareness principle

Before reporting changes, check if anything actually changed. Don't report no-ops.

CommandLogger Architecture

APM is a large and growing CLI with 10+ commands, 8+ integrators, and dozens of output sites. The logging architecture enforces Separation of Concerns: commands declare what happened; the logger decides how to render it. This keeps output consistent, testable, and evolvable without shotgun surgery across command files.

The three layers

Changes to output style (colors, symbols, indentation) happen in the logger or rendering layer only — command code is untouched. New output patterns (e.g. a tree sub-item, a package metadata line) become new logger methods, not ad-hoc format strings in commands.

Base class: CommandLogger

src/apm_cli/core/command_logger.py — base for all commands.

Subclass: InstallLogger(CommandLogger)

Install-specific phases. Commands that don't need these use CommandLogger directly.

When to add a new logger method

If a command needs a new output pattern (new indentation level, new semantic meaning, new verbose gate), add a method to CommandLogger or a subclass. Signs you need a new method:

• You're writing _rich_echo(f" Something: {value}", color="dim") in a command file
• You're checking if logger.verbose: before calling _rich_echo in a command
• You're formatting a string with specific indentation that other commands might reuse
• Multiple commands emit the same kind of line (e.g., file lists, auth info)

Rule: No direct _rich_* in commands

Command functions must NOT call _rich_info(), _rich_error(), etc. directly. Use logger.progress(), logger.error(), etc. instead. The _rich_* helpers are internal to the logger and rendering layers.

Exception: Rich tables and panels for display (not lifecycle logging) may use console.print() directly — these are data presentation, not status reporting.

Rule: Every command gets a CommandLogger

Every Click command function must instantiate a CommandLogger (or subclass) and pass it to helpers:

Rule: Verbose gating lives in the logger

Never check if verbose: in command code. Use methods that gate internally:

DiagnosticCollector integration

Access via logger.diagnostics (lazy-initialized). The collector owns the collect-then-render lifecycle:

Visual hierarchy contract

Multi-package operations follow this tree structure:

Key rules:

• [+] package lines are the top-level anchors (green, no indent beyond 2-space)
• Verbose metadata (Auth, Package type) uses 4-space indent, dim color
• Tree items (└─) use 4-space indent, green color, no symbol prefix
• Inline warnings use 4-space indent, yellow color, verbose-only
• Diagnostics summary appears AFTER all packages, not inline (except verbose hints)

Scaling guidance

As the CLI grows, this architecture scales by:

• New commands: Instantiate CommandLogger, use existing methods. Add subclass only if the command has distinct phases (like InstallLogger).
• New output patterns: Add methods to CommandLogger. Every command benefits.
• New integrators: Accept diagnostics= param, push to collector. No direct output.
• Theme changes: Modify rendering layer (console.py). Zero command changes.
• Testing: Mock CommandLogger in tests to assert semantic calls without parsing output strings.

Anti-patterns

1. Warning for non-actionable state — If the user can't do anything about it, use _rich_info or defer to --verbose, not _rich_warning.

2. Inline warnings in loops — Use DiagnosticCollector to collect, then render a grouped summary after the loop.

3. Missing diagnostics parameter — When calling integrators, always pass diagnostics=diagnostics so warnings route to the deferred summary.

4. No emojis, ever — Emojis are completely banned from all CLI output. Use ASCII text symbols from STATUS_SYMBOLS exclusively. This applies to messages, help text, status indicators, and table titles.

5. Inconsistent symbols — Always use STATUS_SYMBOLS dict with symbol= param, not inline characters.

6. Walls of text — Use Rich tables for structured data, panels for grouped content. Break up long output with visual hierarchy (indentation, └─ tree connectors).

7. Direct _rich_* calls in commands — Use logger.start(), logger.progress(), logger.tree_item() etc. The _rich_* helpers are internal to CommandLogger and console.py. Adding a _rich_echo call in a command file is a SoC violation.

8. Manual if verbose: checks — Use logger.verbose_detail(), logger.package_auth(), or other verbose-gated methods. The logger owns the gate.

9. Manual if dry_run: checks — Use logger.should_execute or logger.dry_run_notice().

10. Format strings for indentation in commands — Don't write f" Auth: {source}" in command code. Use logger.package_auth(source) which owns the indent level. When a new indentation pattern is needed, add a method to CommandLogger.

11. Re-creating shared objects per iteration — Expensive objects like AuthResolver should be created once before loops and reused per-package. The logger and diagnostics collector are already singletons per command invocation.

12. Using logger.progress() for tree sub-items — progress() adds a [i] symbol prefix. Tree continuation lines (└─) should use logger.tree_item() which renders with no symbol.*