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

[github-actions]

CLI Consistency Report

Date: 2026-03-31
APM Version: 0.8.8 (6d8cb6f)
Commands Inspected: 38

Summary

Severity	Count
High	3
Medium	5
Low	2

---

High Severity

apm compile --target docs missing valid values copilot and cursor

• Command: apm compile --help
• Problem: The CLI exposes copilot and cursor as valid --target values, but the cli-commands.md reference omits both. Users following the docs would not know they can compile for copilot (the primary non-deprecated value) or cursor.
• Evidence:
  • CLI: -t, --target [copilot|vscode|agents|claude|cursor|opencode|codex|all]
  • Docs (line 1087): -t, --target [vscode|agents|claude|codex|opencode|all]
• Suggested Fix: Update docs/src/content/docs/reference/cli-commands.md line 1087 to:

  -t, --target [copilot|vscode|agents|claude|cursor|opencode|codex|all]
  ```
  
  

---

apm install --target docs missing deprecated aliases vscode and agents

• Command: apm install --help
• Problem: The CLI accepts vscode and agents as valid --target aliases for install, but the docs omit them. While deprecated, they are still functional and should be documented to avoid confusion when users encounter them in existing scripts.
• Evidence:
  • CLI: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  • Docs (line 90): --target [copilot|claude|cursor|codex|opencode|all]
• Suggested Fix: Update the docs option listing to include vscode and agents with a note that they are deprecated aliases for copilot.

---

apm deps tree --global flag undocumented

• Command: apm deps tree --help
• Problem: apm deps tree accepts a -g, --global flag that shows the user-scope dependency tree, but the docs describe the command as having no options at all.
• Evidence:
  • CLI help output:

    Options:
      -g, --global  Show user-scope dependency tree (~/.apm/)
      --help        Show this message and exit.
    

  • Docs (line 651-657): apm deps tree section lists no options and shows no --global flag.
• Suggested Fix: Add --global option to the apm deps tree section in docs.

---

Medium Severity

apm uninstall -v/--verbose flag missing from docs

• Command: apm uninstall --help
• Problem: The CLI exposes -v, --verbose for apm uninstall, but the docs option list for apm uninstall does not document this flag.
• Evidence:
  • CLI: -v, --verbose Show detailed removal information
  • Docs (line 279-281): Options list only --dry-run and -g, --global
• Suggested Fix: Add - -v, --verbose - Show detailed removal information to the apm uninstall options in docs.

---

apm run and apm preview -v/--verbose flag missing from docs

• Command: apm run --help, apm preview --help
• Problem: Both apm run and apm preview expose -v, --verbose in the CLI, but neither command's docs section documents this flag.
• Evidence:
  • CLI: -v, --verbose Show detailed output (both commands)
  • Docs apm run (line 1010-1013): Only lists -p, --param TEXT
  • Docs apm preview (line 1044): Only lists -p, --param TEXT
• Suggested Fix: Add - -v, --verbose - Show detailed output to both apm run and apm preview option sections.

---

apm deps update -g short flag not shown in docs

• Command: apm deps update --help
• Problem: The CLI exposes -g, --global for apm deps update, but the docs only mention --global without the -g short form.
• Evidence:
  • CLI: -g, --global Update user-scope dependencies (~/.apm/)
  • Docs (line 754): --target, -t - ... (has short form for --target but not for --global); the --global option is not even listed in the docs options table for this command
• Suggested Fix: Add - -g, --global - Update user-scope dependencies (~/.apm/) to the apm deps update options section.

---

apm update docs show non-ASCII emoji in example CLI output

• Command: apm update (version check warning)
• Problem: The docs show ⚠️ emoji in the example of the auto-update warning message. The actual CLI outputs ASCII bracket notation [!] via _rich_warning(..., symbol="warning"), consistent with the project's ASCII-only output rule. The docs example misrepresents what the CLI actually prints.
• Evidence:
  • Docs (lines 584-587):

    ⚠️  A new version of APM is available: 0.7.0 (current: 0.6.3)
    Run apm update to upgrade
    

  • Source code (src/apm_cli/commands/_helpers.py:257): Uses _rich_warning(f"A new version of APM is available: ...", symbol="warning") which emits [!] prefix (from STATUS_SYMBOLS["warning"] = "[!]" in console.py:40)
• Suggested Fix: Update the docs example to:

  [!] A new version of APM is available: 0.7.0 (current: 0.6.3)
  Run apm update to upgrade
  

---

Low Severity

apm audit --verbose help text description differs between CLI and docs

• Command: apm audit --help
• Problem: The short description of --verbose in the CLI help does not match the description in the docs.
• Evidence:
  • CLI: Show all findings including harmless ones
  • Docs (line 369): Show info-level findings and file details
• Suggested Fix: Align to one consistent description. Suggested: Show info-level findings and file details (more precise).

---

apm audit --strip help text description differs between CLI and docs

• Command: apm audit --help
• Problem: The CLI help and docs describe what --strip preserves using different terms.
• Evidence:
  • CLI: Remove hidden characters from scanned files (preserves emoji and whitespace)
  • Docs (line 368): Remove dangerous characters (critical + warning severity) while preserving info-level content like emoji. ZWJ inside emoji sequences is preserved.
• Suggested Fix: Update the CLI help text to be more precise: Remove dangerous hidden characters while preserving emoji and whitespace.

---

Clean Areas

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

• Error handling: All commands produce sensible Error: ... messages with no stack traces on invalid input
• --help / -h: Works correctly on every command and subcommand
• --dry-run: Present and consistently named across install, uninstall, compile, pack, unpack, prune, audit, deps clean, deps update
• --force: Consistently named and described across install, deps update, pack, unpack
• -y, --yes: Consistent across init, deps clean, marketplace remove
• -v, --verbose: Always spelled -v, --verbose with no naming inconsistencies
• apm config (set, get) — docs match CLI
• apm mcp (list, search, show) — docs match CLI
• apm runtime (setup, list, remove, status) — docs match CLI
• apm marketplace (add, browse, list, remove, update) — docs match CLI
• apm deps list, apm deps info, apm deps clean — docs match CLI
• apm init, apm prune, apm search, apm pack, apm unpack — docs match CLI

Generated by CLI Consistency Checker · ◷

• expires on Apr 2, 2026, 1:37 PM UTC