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

# Bad — inline warning repeated per file, clutters output
for file in files:
    if collision:
        _rich_warning(f"Skipping {file}...")

# Good — collect during loop, render grouped summary at the end
for file in files:
    if collision:
        diagnostics.skip(file, package=pkg_name)

# Later, after the loop:
if diagnostics.has_diagnostics:
    diagnostics.render_summary()

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.

from apm_cli.utils.console import (
    _rich_success, _rich_error, _rich_warning, _rich_info, _rich_echo
)

_rich_success("Installed 3 APM dependencies")        # green, bold
_rich_info("  └─ 2 prompts integrated → .github/prompts/")  # blue
_rich_warning("Config drift detected — re-run apm install")  # yellow
_rich_error("Failed to download package")              # red
_rich_echo("    [pkg-name]", color="dim")              # dim, for verbose details

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

_rich_info("Starting operation...", symbol="gear")     # renders as "[*] Starting operation..."

Output structure pattern

Follow this visual hierarchy for multi-package operations:

[checkmark] package-name-1                      # _rich_success — download/copy ok
  [tree] 2 prompts integrated → .github/prompts/     # _rich_info — indented summary
  [tree] 1 skill(s) integrated → .github/skills/
[checkmark] package-name-2
  [tree] 1 instruction(s) integrated → .github/instructions/

── Diagnostics ──                         # Only if diagnostics.has_diagnostics
  [warning] N files skipped — ...                   # Grouped by category
    Run with --verbose to see details

Installed 2 APM dependencies              # _rich_success — final summary

Content-awareness principle

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

# Bad — always copies and reports, even when content is identical
shutil.rmtree(target)
shutil.copytree(source, target)
_rich_info(f"  └─ Skill updated")

# Good — skip when content matches
if SkillIntegrator._dirs_equal(source, target):
    continue  # Nothing changed, nothing to report

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

┌─────────────────────────────────────────────────────┐
│  Command layer  (install.py, pack.py, audit.py …)   │
│  Calls: logger.success(), logger.tree_item(), …      │
│  NEVER calls: _rich_*, click.echo(), print()         │
├─────────────────────────────────────────────────────┤
│  Logger layer   (command_logger.py)                  │
│  CommandLogger ← InstallLogger, future subclasses    │
│  Owns: verbose gating, symbol choice, indentation    │
│  Delegates to: _rich_* helpers                       │
├─────────────────────────────────────────────────────┤
│  Rendering layer (console.py)                        │
│  _rich_echo, _rich_success, _rich_error, …           │
│  Owns: Rich/colorama fallback, color, STATUS_SYMBOLS │
└─────────────────────────────────────────────────────┘

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.