[cli-consistency] CLI Consistency Report -- 2026-04-13

[github-actions]

CLI Consistency Report

Date: 2026-04-13
APM Version: 0.8.11 (40621bf)
Commands Inspected: 39 (20 top-level + 19 subcommands across deps, mcp, config, runtime, marketplace groups)

Summary

Severity	Count
High	0
Medium	4
Low	1

---

Medium Severity

Trailing period on apm outdated and apm view descriptions in top-level help

• Commands: apm outdated, apm view
• Problem: Both commands have trailing periods in their one-line descriptions shown by apm --help, while all 18 other top-level commands do not. This is a style inconsistency that creates visual noise.
• Evidence (from apm --help):

  outdated     Show outdated locked dependencies.
  view         View package metadata or list remote versions.
  ```
  vs. every other command:
  ```
  audit        Scan installed packages for hidden Unicode characters
  compile      Compile APM context into distributed AGENTS.md files
  install      Install APM and MCP dependencies (auto-creates apm.yml...
  

• Suggested Fix: Remove the trailing periods from the help= strings of apm outdated and apm view in the CLI source.

---

apm install docs omit the -v short flag for --verbose

• Command: apm install
• Problem: The CLI exposes -v, --verbose for apm install, but the documentation (docs/src/content/docs/reference/cli-commands.md, line 95) lists the option as --verbose only, hiding the short flag from users.
• Evidence:
  • CLI (apm install --help): -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 docs to - `-v, --verbose` - Show individual file paths... to match the pattern used for every other verbose option in the same reference page.

---

apm install --target docs omit deprecated vscode and agents values

• Command: apm install
• Problem: The docs list valid target values as [copilot|claude|cursor|codex|opencode|all], but the CLI also accepts vscode and agents (deprecated aliases for copilot). Users who pass these values from old scripts or guides will get no documentation warning.
• Evidence:
  • CLI (apm install --help): -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  • Docs (line 90): - `--target [copilot|claude|cursor|codex|opencode|all]` - Force deployment to a specific target
• Suggested Fix: Update the docs to include vscode and agents in the value list with a deprecation note, e.g. [copilot|claude|cursor|codex|opencode|vscode|agents|all] and add: 'vscode' and 'agents' are deprecated aliases for 'copilot'.

---

apm runtime remove --yes lacks -y short flag; inconsistent with similar commands

• Command: apm runtime remove
• Problem: apm runtime remove accepts only --yes with no -y shorthand, while apm deps clean and apm marketplace remove both expose -y, --yes. Users scripting unattended workflows will notice the inconsistency.
• Evidence:
  • apm runtime remove --help: --yes Confirm the action without prompting (no -y)
  • apm deps clean --help: -y, --yes Skip confirmation prompt
  • apm marketplace remove --help: -y, --yes Skip confirmation
• Suggested Fix: Add -y as a short flag alias for --yes in the apm runtime remove command implementation.

---

Low Severity

apm deps update docs list --verbose before -v (reversed flag order)

• Command: apm deps update
• Problem: The documentation (docs/src/content/docs/reference/cli-commands.md, line 833) describes the verbose flag as --verbose, -v (long form first), while every other command on the same page uses the standard short-first format -v, --verbose. Minor inconsistency but creates a jarring read.
• Evidence:
  • Line 833: - `--verbose, -v` - Show detailed update information
  • All other pages: - `-v, --verbose` - Show detailed output
• Suggested Fix: Change line 833 to - `-v, --verbose` - Show detailed update information to match the project-wide convention.

---

Clean Areas

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

• Core commands: apm init, apm compile, apm run, apm preview, apm list, apm uninstall, apm update, apm prune, apm audit, apm pack, apm unpack
• deps subcommands: apm deps list, apm deps tree, apm deps info, apm deps clean, apm deps update
• mcp subcommands: apm mcp list, apm mcp search, apm mcp show
• config subcommands: apm config (bare), apm config get, apm config set
• runtime subcommands: apm runtime setup, apm runtime list, apm runtime status
• marketplace subcommands: apm marketplace add, apm marketplace browse, apm marketplace list, apm marketplace remove, apm marketplace update
• top-level: apm search, apm view, apm outdated
• Error handling: All tested invalid-argument cases (--nonexistent-flag, missing required args) produce clean error messages with usage hints -- no stack traces observed.
• Flag naming: --dry-run, --force, --global/-g, --verbose/-v are consistently named across all commands that support them (with the exceptions noted above).
• --help / -h: Works on every command and subcommand tested.
• ASCII compliance: All help text stays within printable ASCII; no Unicode, emoji, or box-drawing characters observed.

Generated by CLI Consistency Checker · ◷

• expires on Apr 15, 2026, 1:40 PM UTC