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

[github-actions]

CLI Consistency Report

Date: 2026-03-26
APM Version: 0.8.5 (fdd0003)
Commands Inspected: 31

Summary

Severity	Count
High	1
Medium	2
Low	0

---

High Severity

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

• Commands affected: apm --version, apm config, apm runtime list, and any command that renders a Rich Panel or Table without an ASCII-safe box style
• Problem: The project's encoding rule requires all CLI output to stay within printable ASCII (U+0020-U+007E). However, apm --version outputs 726 non-ASCII bytes, apm config outputs 648 non-ASCII bytes, and apm runtime list outputs 1,209 non-ASCII bytes — all from Rich's default Unicode box-drawing characters (e.g., \u256d, \u2500, \u2570, \u2502). On Windows terminals using the cp1252 codepage, this raises UnicodeEncodeError: 'charmap' codec can't encode character.
• Evidence:

  $ apm --version | cat -v
  M-bM-^UM--M-bM-^TM-^@...   # Unicode box-drawing characters (U+256D, U+2500, etc.)
  M-bM-^TM-^B Agent Package Manager (APM) CLI version 0.8.5 (fdd0003) M-bM-^TM-^B
  M-bM-^UM-0M-bM-^TM-^@...
  

  Source: src/apm_cli/commands/_helpers.py:229 uses console.print(Panel(version_text, border_style="cyan", padding=(0, 1))) which renders with Rich's default rounded Unicode box style. apm config and apm runtime list use Rich Table with default box styles.
• Suggested Fix: Create the Rich Console with safe_box=True in src/apm_cli/utils/console.py — this forces Rich to use ASCII box characters on all platforms:

  return Console(safe_box=True)
  ```
  Alternatively, pass `box=box.ASCII` or `box=box.MINIMAL` explicitly to every `Panel` and `Table` call.

---

Medium Severity

apm compile --target docs missing copilot and cursor values

• Command: apm compile --target
• Problem: The CLI reference documentation lists the target option as [vscode|agents|claude|opencode|all], omitting copilot and cursor which are valid values in the actual CLI.
• Evidence:
  • Docs (docs/src/content/docs/reference/cli-commands.md, line 908): - `-t, --target [vscode|agents|claude|opencode|all]` - Target agent format. `agents` is an alias for `vscode`. Auto-detects if not specified.
  • CLI actual output: -t, --target [copilot|vscode|agents|claude|cursor|opencode|all]
• Suggested Fix: Update the docs to list all valid values: [copilot|vscode|agents|claude|cursor|opencode|all], and note that copilot is the canonical name, vscode and agents are deprecated aliases.

---

Multiple commands have undocumented -v, --verbose flag

• Commands affected: apm uninstall, apm preview, apm unpack, apm pack
• Problem: All four commands expose a -v, --verbose flag in the CLI, but the flag is not mentioned in the CLI reference documentation for any of them.
• Evidence:

  $ apm uninstall --help
  Options:
    --dry-run      Show what would be removed without removing
    -v, --verbose  Show detailed removal information   # <-- not in docs
    --help         Show this message and exit.
  

  $ apm preview --help
  Options:
    -p, --param TEXT  Parameter in format name=value
    -v, --verbose     Show detailed output             # <-- not in docs
    --help            Show this message and exit.
  

  $ apm unpack --help
  Options:
    -o, --output PATH  Target directory (default: current directory).
    --skip-verify      Skip bundle completeness check.
    --dry-run          Show what would be unpacked without writing.
    --force            Deploy despite critical hidden-character findings.
    -v, --verbose      Show detailed unpacking information  # <-- not in docs
    --help             Show this message and exit.
  

  $ apm pack --help
  Options:
    ...
    -v, --verbose      Show detailed packing information  # <-- not in docs
    --help             Show this message and exit.
  

  Docs for these commands only list --dry-run (and other flags) under Options, with no mention of --verbose.
• Suggested Fix: Add - -v, --verbose - Show detailed output to the Options section for apm uninstall, apm preview, apm unpack, and apm pack in docs/src/content/docs/reference/cli-commands.md.

---

Clean Areas

The following commands and areas passed all checks:

• Error handling: All tested invalid-argument cases produce clean, non-stack-trace error messages (apm install --nonexistent-flag, apm deps info with no arg, apm config set with no args, apm mcp show with no arg).
• apm deps subcommands: All options documented and consistent; --yes / -y flag on apm deps clean is documented correctly.
• apm mcp subcommands: apm mcp list, apm mcp search, apm mcp show — help text and docs are aligned. --limit defaults (10 for search, 20 for list) match between CLI and docs.
• apm config subcommands: apm config get, apm config set — documented correctly; bare apm config displaying current settings works as documented.
• apm runtime subcommands: apm runtime setup, apm runtime list, apm runtime remove, apm runtime status — all match documentation.
• apm compile: All flags documented except the --target discrepancy noted above.
• apm install: All flags documented (note: vscode and agents deprecated aliases for --target are present in CLI but absent from docs — covered in medium findings above).
• apm audit: All flags (--file, --strip, --dry-run, --verbose, --format, --output, --ci, --policy, --no-cache, --no-fail-fast) are documented correctly.
• apm init: -y, --yes and --plugin flags are documented correctly.
• apm prune: --dry-run is the only flag; documented correctly.
• Flag naming consistency: --dry-run, --force, --verbose/-v, --yes/-y are consistently named across all commands that use them.
• --help / -h: Works on every command and subcommand tested.

Generated by CLI Consistency Checker · ◷

• expires on Mar 28, 2026, 1:39 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-03-28T13:39:06.611Z.

Closed by Workflow