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

[github-actions]

CLI Consistency Report

Date: 2026-03-25
APM Version: 0.8.5 (52e9b1b)
Commands Inspected: 31 (+ 2 non-existent commands attempted: apm mcp install, apm config list)

Summary

Severity	Count
High	1
Medium	4
Low	2

---

High Severity

apm --version outputs non-ASCII box-drawing characters

• Command: apm --version
• Problem: The version banner renders a Rich panel using box-drawing characters (╭, ─, ╮, │, ╰), which are multi-byte UTF-8 characters outside the printable ASCII range (U+0020–U+007E). The project's own encoding rule explicitly bans "Unicode box-drawing characters" from all CLI output to prevent charmap codec errors on Windows cp1252 terminals.
• Evidence:

  ╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
  │ Agent Package Manager (APM) CLI version 0.8.5 (52e9b1b)                                                              │
  ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
  ```
  Confirmed non-ASCII bytes via `od -c`: the `╭` character encodes as `342 225 255` (3-byte UTF-8 sequence).
  

• Suggested Fix: Replace the Rich panel in the version banner with plain ASCII output, e.g.:

  Agent Package Manager (APM) CLI version 0.8.5 (52e9b1b)
  

  Or use [+] Agent Package Manager (APM) version 0.8.5 per the project's bracket-status convention.

---

Medium Severity

apm compile --target documentation is incomplete and semantically incorrect

• Command: apm compile --help
• Problem: The CLI reference documents --target options as [vscode|agents|claude|opencode|all], but the actual CLI exposes [copilot|vscode|agents|claude|cursor|opencode|all]. Two values are entirely missing from the docs (copilot and cursor). Additionally, the docs describe agents as an alias for vscode, but the CLI's help text says the opposite: 'vscode' and 'agents' are deprecated aliases for 'copilot'. This is a semantic reversal of the primary vs. alias relationship.
• Evidence:
  • CLI (apm compile --help): -t, --target [copilot|vscode|agents|claude|cursor|opencode|all] with note 'vscode' and 'agents' are deprecated aliases for 'copilot'
  • Docs (cli-commands.md line 907): -t, --target [vscode|agents|claude|opencode|all] with note 'agents' is an alias for 'vscode'
• Suggested Fix: Update cli-commands.md to list all valid targets (copilot, vscode, agents, claude, cursor, opencode, all) and correct the alias description to match the CLI: 'vscode' and 'agents' are deprecated aliases for 'copilot'.

---

-v short flag for --verbose undocumented in several commands

• Commands: apm init, apm uninstall, apm mcp list, apm mcp show
• Problem: All four commands expose -v as a short flag for --verbose in their CLI help output, but the CLI reference documentation omits the -v short form for each. (apm install also omits -v from its docs.) Users reading the docs would not know about the short flag.
• Evidence:
  • apm init --help: -v, --verbose Show detailed output
  • apm uninstall --help: -v, --verbose Show detailed removal information
  • apm mcp list --help: -v, --verbose Show detailed output
  • apm mcp show --help: -v, --verbose Show detailed output
  • Docs (cli-commands.md): None of these four commands mention -v in their options sections. For apm install, docs list --verbose without the -v alias.
• Suggested Fix: Add -v short form to the documented options for apm init, apm uninstall, apm mcp list, apm mcp show, and apm install in cli-commands.md.

---

apm config get returns undocumented default_client key

• Command: apm config get
• Problem: Running apm config get with no argument outputs a default_client configuration key (value vscode) that is not documented anywhere in the CLI reference. The docs state that the only supported key for apm config get/set is auto-integrate. The default_client key is real and functional in the codebase (src/apm_cli/config.py), but is invisible to users consulting the documentation.
• Evidence:

  $ apm config get
  [i] APM Configuration:
    default_client: vscode
  

  Docs (cli-commands.md line 1092): Supported keys: auto-integrate — Whether to automatically integrate .prompt.md files into AGENTS.md
  Source (src/apm_cli/config.py line 20): json.dump({"default_client": "vscode"}, f)
• Suggested Fix: Document default_client as a supported configuration key in the apm config get/set sections, including its accepted values (vscode, copilot, etc.) and its effect on behavior.

---

apm update version notification example contains non-ASCII emoji

• File: docs/src/content/docs/reference/cli-commands.md line 572
• Problem: The documentation example showing the automatic update notification uses ⚠️ (U+26A0 WARNING SIGN + U+FE0F VARIATION SELECTOR-16). These are non-ASCII code points. The project's encoding rules state that markdown documentation files must also stay within printable ASCII and must use [!] for warnings instead of emoji.
• Evidence:

  ⚠️  A new version of APM is available: 0.7.0 (current: 0.6.3)
  

  (from cli-commands.md line 572)
• Suggested Fix: Replace ⚠️ with [!] per the project's bracket-status convention:

  [!] A new version of APM is available: 0.7.0 (current: 0.6.3)
  

---

Low Severity

apm deps update has no actionable options and minimal help text

• Command: apm deps update --help
• Problem: The apm deps update command exposes only --help (no --dry-run, --verbose, or --yes), making it inconsistent with sibling commands like apm deps clean (which has --dry-run and -y). There is also no description of what "update" means (fetch latest commit? respect version pins?), leaving users without guidance.
• Evidence:

  Usage: apm deps update [OPTIONS] [PACKAGE]
    Update APM dependencies
  Options:
    --help  Show this message and exit.
  

  Compare with apm deps clean --help which documents --dry-run and -y, --yes.
• Suggested Fix: Add --dry-run and -v, --verbose flags to apm deps update to match the style of other deps subcommands. Update help text to clarify update semantics.

---

apm deps list and apm deps tree offer no options

• Commands: apm deps list, apm deps tree
• Problem: Both commands expose only --help with no filtering, formatting, or verbosity options. Other deps subcommands (clean, update) accept optional arguments. While not broken, the lack of even --verbose or --format flags may limit usability and is inconsistent with the richer option sets on peer commands.
• Evidence:

  Usage: apm deps list [OPTIONS]
    List installed APM dependencies
  Options:
    --help  Show this message and exit.
  

  Usage: apm deps tree [OPTIONS]
    Show dependency tree structure
  Options:
    --help  Show this message and exit.
  

• Suggested Fix: Consider adding at least -v, --verbose to apm deps list and apm deps tree to allow richer output, consistent with other commands.

---

Clean Areas

The following commands and areas passed all checks with no issues found:

• apm init — correct usage, args, and behavior documentation (minus undocumented -v flag noted above)
• apm install — comprehensive documentation, all major options present and accurate
• apm uninstall — accurate and consistent (minus undocumented -v flag noted above)
• apm prune — accurate and consistent
• apm run — accurate and consistent
• apm preview — accurate and consistent
• apm audit — comprehensive documentation, all options match CLI output
• apm pack — accurate and consistent
• apm unpack — accurate and consistent
• apm list — accurate and consistent
• apm deps info — accurate and consistent
• apm deps clean — accurate and consistent
• apm mcp search — accurate and consistent
• apm mcp show — accurate (minus undocumented -v flag)
• apm mcp list — accurate (minus undocumented -v flag)
• apm config set / apm config get — functionally accurate (minus undocumented key)
• apm runtime setup, list, remove, status — accurate and consistent
• Error handling: all commands tested with invalid arguments produce clean error messages (no stack traces)
• Exit behavior: all tested invalid-argument scenarios exit with code 2 and helpful usage text

Generated by CLI Consistency Checker · ◷

• expires on Mar 27, 2026, 1:36 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-03-27T13:36:12.537Z.

Closed by Workflow