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

[github-actions]

CLI Consistency Report

Date: 2026-04-16
APM Version: 0.8.11 (a61bc0f)
Commands Inspected: 40

Summary

Severity	Count
High	1
Medium	3
Low	3

---

High Severity

apm compile --target docs list outdated/wrong target values

• Command: apm compile
• Problem: The CLI reference documentation lists [vscode|agents|claude|codex|opencode|all] as the valid --target values, but the actual CLI offers [copilot|claude|cursor|opencode|codex|vscode|agents|all]. The docs omit copilot (the current non-deprecated primary option) and cursor entirely. The docs still present vscode as the primary target name, even though it is now a deprecated alias for copilot. The auto-detection table in docs also uses only vscode column values.
• Evidence:
  • CLI help output: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all] Target platform: copilot (AGENTS.md), claude (CLAUDE.md), cursor, opencode, or all. 'vscode' and 'agents' are deprecated aliases
  • docs/src/content/docs/reference/cli-commands.md line 1178: - \-t, --target [vscode|agents|claude|codex|opencode|all]` - Target agent format. `agents` is an alias for `vscode`. Auto-detects if not specified.`
  • Same doc line 1243 example: apm compile --target vscode # AGENTS.md + .github/ only (no example with --target copilot)
• Suggested Fix: Update the compile docs to list [copilot|claude|cursor|opencode|codex|vscode|agents|all], note that vscode and agents are deprecated aliases for copilot, add an example using --target copilot, and update the auto-detection table to show copilot as the resolved target name.

---

Medium Severity

apm runtime remove missing -y shorthand for --yes

• Command: apm runtime remove
• Problem: The --yes flag on apm runtime remove has no -y short form, making it inconsistent with every other confirmation-skip flag in the CLI.
• Evidence:
  • apm runtime remove --help: --yes Confirm the action without prompting (no -y)
  • apm init --help: -y, --yes Skip interactive prompts and use auto-detected defaults
  • apm deps clean --help: -y, --yes Skip confirmation prompt
  • apm marketplace remove --help: -y, --yes Skip confirmation
• Suggested Fix: Add -y as a shorthand for --yes in the runtime remove command definition in the source code.

---

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

• Command: apm install
• Problem: The CLI reference docs list only [copilot|claude|cursor|codex|opencode|all] for --target, but the CLI actually accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all]. Users with older automation scripts using --target vscode won't find any mention of it in the install docs.
• Evidence:
  • CLI help: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  • docs/src/content/docs/reference/cli-commands.md line 90: - \--target [copilot|claude|cursor|codex|opencode|all]``
• Suggested Fix: Update the install docs to add vscode and agents to the accepted --target values with a deprecation note: --target [copilot|claude|cursor|opencode|codex|vscode|agents|all] — note vscode and agents are deprecated aliases for copilot.

---

apm pack --target docs omit agents deprecated value

• Command: apm pack
• Problem: The pack docs list [copilot|vscode|claude|cursor|codex|opencode|all] for --target but the CLI also accepts agents.
• Evidence:
  • CLI help: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  • docs/src/content/docs/reference/cli-commands.md line 464: - \-t, --target [copilot|vscode|claude|cursor|codex|opencode|all]``
• Suggested Fix: Add agents to the documented --target values for apm pack with a deprecation note.

---

Low Severity

apm outdated description has a trailing period

• Command: apm outdated
• Problem: The command's one-line description ends with a period, unlike every other command in the CLI.
• Evidence:
  • apm outdated --help: Show outdated locked dependencies. (trailing period)
  • Other commands for comparison: apm deps tree --help: Show dependency tree structure (no period); apm list --help: List available scripts in the current project (no period)
• Suggested Fix: Remove the trailing period from the apm outdated help string.

---

apm config bare command behavior is undocumented

• Command: apm config (invoked without a subcommand)
• Problem: Running apm config without a subcommand displays a useful configuration summary table (project status, APM version, auto-integrate setting), but this behavior is not mentioned anywhere in the CLI reference documentation.
• Evidence:
  • Actual output: A rich table titled "Current APM Configuration" with Project and Global sections.
  • docs/src/content/docs/reference/cli-commands.md apm config section: only documents config get and config set; no mention of the bare apm config behaviour.
• Suggested Fix: Add a short apm config (bare) entry to the CLI reference docs describing its output and examples.

---

apm mcp list and apm mcp search have inconsistent default limits

• Command: apm mcp list, apm mcp search
• Problem: apm mcp list defaults to 20 results while apm mcp search defaults to 10. This asymmetry is not explained and may confuse users who expect both to behave similarly.
• Evidence:
  • apm mcp list --help: --limit INTEGER Number of results to show [default: 20]
  • apm mcp search --help: --limit INTEGER Number of results to show [default: 10]
• Suggested Fix: Either align both defaults to the same value (e.g., 10 or 20), or document why they differ (e.g., search is more targeted so a smaller default makes sense). The docs should explicitly state the default for each.

---

Clean Areas

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

• apm init -- help text, flags (-y/--yes, -v/--verbose, --plugin), and docs are consistent.
• apm install -- all flags present and functional; error handling is clean.
• apm uninstall -- flags and docs consistent.
• apm update -- minimal flags, consistent with docs.
• apm run / apm preview -- flag symmetry is correct.
• apm list -- no flags needed, consistent.
• apm deps group -- list, tree, info, clean, update all consistent with docs.
• apm mcp group -- list, search, show consistent with docs (no mcp install is documented, confirming it should not exist).
• apm config set / apm config get -- args and behavior match docs.
• apm runtime setup, apm runtime list, apm runtime status -- consistent with docs.
• apm audit -- all flags (--strip, --dry-run, --ci, --policy, --format, -o) match docs.
• apm marketplace group -- all five subcommands (add, browse, list, remove, update) match docs.
• apm outdated -- flags consistent (apart from trailing period in description).
• apm search -- consistent with docs.
• apm view -- consistent with docs.
• apm pack -- consistent (apart from undocumented agents target value).
• apm unpack -- consistent with docs.
• apm prune -- consistent with docs.
• Error handling -- all tested commands (apm install --nonexistent-flag, apm deps info without args, apm config set without args) produce clean error messages with no stack traces.

Generated by CLI Consistency Checker · ◷

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