[cli-consistency] CLI Consistency Report — 2026-03-30

[github-actions]

CLI Consistency Report

Date: 2026-03-30
APM Version: 0.8.6 (b56c537)
Commands Inspected: 31

Summary

Severity	Count
High	1
Medium	3
Low	4

---

High Severity

Non-ASCII box-drawing characters in CLI output (Windows cp1252 breakage)

• Commands: apm --version, apm runtime list, apm deps tree, and any command using Rich-rendered tables or diagnostics
• Problem: Multiple commands emit Unicode box-drawing and tree characters (╭ ╰ │ ─ └─ ├─ ──) directly in their output. The project's own encoding rules state: "All source code and CLI output must stay within printable ASCII (U+0020–U+007E)" and "Windows cp1252 terminals raise UnicodeEncodeError for any character outside cp1252." These characters are hardcoded in source output strings and rendered via Rich tables.
• Evidence:
  • apm --version output (verified via cat -v): panel rendered with ╭─…─╮ / │ … │ / ╰─…─╯ box-drawing chars.
  • apm runtime list output: Rich table with ┌ ─ ┐ │ ├ ┤ └ ┘ table borders.
  • Source files containing non-ASCII in output strings:
    • src/apm_cli/utils/diagnostics.py lines 226, 229, 232: "── Diagnostics ──" and f" └─ {d.message}" (lines 283, 297, 311, 333, 349, 358, 366, 374)
    • src/apm_cli/commands/install.py lines 829–830: f" └─ Inspect source: …", " └─ Use --force to deploy anyway"
• Suggested Fix: Replace ── with --, └─ with , ├─ with +-, and the Rich Panel/Table renderings in --version and table commands with ASCII equivalents. For --version, use plain click.echo() with [*] prefix. For tables, either configure Rich to use ASCII borders (box=box.ASCII) or use plain formatted output.

---

Medium Severity

apm install --target docs missing vscode and agents values

• Command: apm install --help
• Problem: The CLI accepts [copilot|claude|cursor|opencode|vscode|agents|all] for --target, but the documentation at docs/src/content/docs/reference/cli-commands.md line 90 only lists [copilot|claude|cursor|opencode|all], omitting vscode and agents.
• Evidence:
  • CLI help: -t, --target [copilot|claude|cursor|opencode|vscode|agents|all]
  • Docs line 90: - `--target [copilot|claude|cursor|opencode|all]` - Force deployment to a specific target
• Suggested Fix: Update docs line 90 to: - `--target [copilot|claude|cursor|opencode|vscode|agents|all]` - Force deployment to a specific target (overrides auto-detection). `vscode` and `agents` are deprecated aliases for `copilot`

apm compile --target docs missing copilot and cursor values

• Command: apm compile --help
• Problem: The CLI accepts [copilot|vscode|agents|claude|cursor|opencode|all] for --target, but the documentation at line 908 lists only [vscode|agents|claude|opencode|all], omitting copilot and cursor.
• Evidence:
  • CLI help: -t, --target [copilot|vscode|agents|claude|cursor|opencode|all]
  • Docs line 908: - `-t, --target [vscode|agents|claude|opencode|all]`
• Suggested Fix: Update docs line 908 to include copilot and cursor in the enum list.

Non-ASCII emojis in cli-commands.md documentation

• Problem: The documentation file docs/src/content/docs/reference/cli-commands.md contains emoji characters that violate the project's ASCII-only encoding rule. These appear in code blocks and output examples, implying the CLI emits them — which it does not.
• Evidence:
  • Line 573: ⚠️ A new version of APM is available: … (in a version-check example)
  • Line 1210: - Installation status (✅ Installed / ❌ Not installed) (in apm runtime list output description)
• Suggested Fix: Replace line 573 with [!] A new version of APM is available: 0.7.0 (current: 0.6.3) and line 1210 with - Installation status ([+] Installed / [ ] Not installed) per the project's STATUS_SYMBOLS convention.

---

Low Severity

apm uninstall --verbose flag missing from docs

• Command: apm uninstall --help
• Problem: The CLI exposes -v, --verbose (Show detailed removal information) but docs/src/content/docs/reference/cli-commands.md lines 272–274 only document --dry-run.
• Evidence:
  • CLI help: -v, --verbose Show detailed removal information
  • Docs lines 272–274: only --dry-run listed under Options
• Suggested Fix: Add - -v, --verbose - Show detailed removal information to the apm uninstall Options section in docs.

apm init --verbose flag missing from docs

• Command: apm init --help
• Problem: The CLI exposes -v, --verbose but docs/src/content/docs/reference/cli-commands.md lines 36–38 only list -y, --yes and --plugin under Options.
• Evidence:
  • CLI help: -v, --verbose Show detailed output
  • Docs lines 36–38: no --verbose listed
• Suggested Fix: Add - -v, --verbose - Show detailed output to the apm init Options section in docs.

apm install --verbose help description drift

• Command: apm install --help
• Problem: The CLI help text says "Show detailed installation information", while the documentation provides a more specific description: "Show individual file paths and full error details in the diagnostic summary". Minor wording inconsistency.
• Evidence:
  • CLI: -v, --verbose Show detailed installation information
  • Docs line 95: - `--verbose` - Show individual file paths and full error details in the diagnostic summary
• Suggested Fix: Update the CLI help string for --verbose in apm install to: "Show individual file paths and full error details" (or align docs to match CLI).

apm install --verbose docs omit -v shorthand

• Command: apm install --help
• Problem: Docs line 95 lists --verbose without the -v shorthand, while all other commands consistently show the short flag. Inconsistent style.
• Evidence:
  • Docs line 95: - `--verbose` - Show individual…
  • CLI: -v, --verbose
  • Compare: docs for audit line 359 correctly shows - `-v, --verbose`
• Suggested Fix: Update docs line 95 to - `-v, --verbose` - Show individual…

---

Clean Areas

• apm init, apm deps (all subcommands), apm config set/get, apm runtime setup/remove/status: help text is clear, well-structured, and matches docs.
• apm pack, apm unpack, apm prune, apm audit: help text is thorough with good option coverage and matches docs.
• apm mcp list/search/show: consistent flag naming, accurate docs.
• All commands produce clean, actionable error messages on invalid input (no stack traces observed).
• --dry-run flag naming is consistent across all commands that support it (install, uninstall, pack, unpack, prune, deps clean, audit).
• --help / -h works correctly on every inspected command and subcommand.

Generated by CLI Consistency Checker · ◷

• expires on Apr 1, 2026, 1:38 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-04-01T13:38:32.811Z.

Closed by Workflow