[cli-consistency] CLI Consistency Report — 2026-04-15

[github-actions]

CLI Consistency Report

Date: 2026-04-15
APM Version: 0.8.11 (1e01f92)
Commands Inspected: 37

All findings are backed by real CLI output obtained by running each command during this audit.

Summary

Severity	Count
High	1
Medium	5
Low	1

---

High Severity

apm compile --target documentation is stale — copilot and cursor are missing

• Command: apm compile --help
• Problem: The CLI accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all] but the reference docs list only [vscode|agents|claude|codex|opencode|all]. Two valid values are entirely absent:
  • copilot — the canonical target name that replaced the deprecated vscode/agents aliases (the CLI help text itself says "vscode and agents are deprecated aliases for copilot")
  • cursor — a fully supported target with its own output path (.cursor/)
    In addition, the "Target Formats (explicit)" table in the docs has no row for cursor.
• Evidence — CLI 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
                    for 'copilot'. Auto-detects if not specified.
  ```
  

• Evidence — docs (docs/src/content/docs/reference/cli-commands.md line 1178):

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

  And the Target Formats table (line 1210) has no cursor row.
• Suggested Fix:
  1. Update the option description on line 1178 to [copilot|claude|cursor|opencode|codex|vscode|agents|all], noting vscode/agents are deprecated aliases for copilot.
  2. Add a cursor row to the Target Formats table (.cursor/rules/, .cursor/agents/, .cursor/skills/).

---

Medium Severity

apm update docs show emoji in CLI output example — violates ASCII encoding policy

• Command: apm update
• Problem: The reference docs (line 594) show a version-check warning example that uses ⚠️ (U+26A0 U+FE0F), a non-ASCII character. The actual CLI uses [!] from STATUS_SYMBOLS["warning"], not an emoji. This is both factually wrong and violates the project's cross-platform ASCII encoding rule for docs and CLI output.
• Evidence — docs (cli-commands.md line 594):

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

• Evidence — actual source (src/apm_cli/commands/_helpers.py line 258):

  _rich_warning(
      f"A new version of APM is available: {latest_version} (current: {current_version})",
      symbol="warning",
  )
  ```
  Where `STATUS_SYMBOLS["warning"] = "[!]"`.

• Suggested Fix: Replace the example with the actual output format:

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

---

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

• Command: apm install --help
• Problem: The reference docs (line 90) list --target [copilot|claude|cursor|codex|opencode|all] but the CLI accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all]. Deprecated aliases vscode and agents are not documented, leaving users who try them without a hint that the canonical name is now copilot.
• Evidence — CLI:

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

• Evidence — docs (cli-commands.md line 90):

  --target [copilot|claude|cursor|codex|opencode|all]
  

• Suggested Fix: Update line 90 to include all accepted values and add a note that vscode and agents are deprecated aliases for copilot.

---

apm pack --target docs missing agents deprecated alias

• Command: apm pack --help
• Problem: The reference docs (line 464) list [copilot|vscode|claude|cursor|codex|opencode|all] but the CLI accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all]. The agents alias is undocumented.
• Evidence — CLI:

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

• Evidence — docs (cli-commands.md line 464):

  [copilot|vscode|claude|cursor|codex|opencode|all]
  

• Suggested Fix: Add agents to the documented value list and note it is a deprecated alias.

---

apm deps update --target docs missing codex

• Command: apm deps update --help
• Problem: The reference docs (line 836) describe the target option as accepting copilot, claude, cursor, opencode, vscode, agents, all but the CLI shows [copilot|claude|cursor|opencode|codex|vscode|agents|all]. The codex target is omitted from the docs.
• Evidence — CLI:

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

• Evidence — docs (cli-commands.md line 836):

  --target, -t  - Force deployment to a specific target (copilot, claude, cursor, opencode, vscode, agents, all)
  

• Suggested Fix: Add codex to the documented value list.

---

apm install --verbose short flag -v not documented in CLI reference

• Command: apm install --help
• Problem: The CLI exposes -v, --verbose (with a -v short form) but the reference docs (line 95) document only the long form --verbose with no mention of the -v alias. This is inconsistent with other commands (uninstall, compile, run, etc.) that correctly document -v, --verbose.
• Evidence — CLI:

  -v, --verbose    Show detailed installation information
  

• Evidence — docs (cli-commands.md line 95):

  --verbose - Show individual file paths and full error details in the diagnostic summary
  

• Suggested Fix: Update the docs entry to -v, --verbose.

---

Low Severity

apm outdated one-line description has inconsistent trailing period

• Command: apm outdated
• Problem: The one-line description "Show outdated locked dependencies." ends with a period. No other command in the top-level apm --help listing uses a trailing period (e.g. "Compile APM context into distributed AGENTS.md files", "Create a self-contained bundle from installed dependencies"). This is a minor style inconsistency.
• Evidence:

  outdated     Show outdated locked dependencies.
  compile      Compile APM context into distributed AGENTS.md files
  install      Install APM and MCP dependencies (auto-creates apm.yml...
  

• Suggested Fix: Remove the trailing period from the outdated command's help= string in the CLI source to match the style of all other commands.

---

Clean Areas

The following commands and areas passed all checks without issues:

• apm init, apm uninstall, apm run, apm list, apm preview, apm audit, apm pack, apm unpack, apm prune, apm search, apm view — help text, flags, and documentation are consistent
• apm deps list, apm deps tree, apm deps info, apm deps clean — all correct
• apm mcp list, apm mcp search, apm mcp show — all correct
• apm config set, apm config get — all correct
• apm runtime setup, apm runtime list, apm runtime remove, apm runtime status — all correct
• apm marketplace add/list/browse/update/remove — all correct
• Error handling: all tested invalid inputs produce clean error messages with no stack traces
• ASCII encoding compliance: all actual CLI output uses [+], [!], [x], [i], [*], [>] symbols correctly — the only violation is in a doc example (see Medium Why do we need a GitHub token? #1 above)

Generated by CLI Consistency Checker · ◷

• expires on Apr 17, 2026, 2:24 PM UTC