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

[github-actions]

CLI Consistency Report

Date: 2026-04-09
APM Version: 0.8.11 (5c81b95)
Commands Inspected: 40 (20 top-level + 20 subcommands across deps, mcp, config, runtime, marketplace groups)

Summary

Severity	Count
High	1
Medium	6
Low	2

---

High Severity

apm compile progress message is misleading for cursor, opencode, and codex targets

• Command: apm compile --target cursor, apm compile --target opencode, apm compile --target codex
• Problem: All three targets fall through to the else branch in the compile target-message handler (which is labelled # "all"), producing the message "Compiling for AGENTS.md + CLAUDE.md". This is factually incorrect for cursor (.cursor/agents/ + .cursor/skills/ + .cursor/rules/), opencode (.opencode/agents/ + .opencode/commands/), and codex (.agents/skills/ + .codex/agents/ + .codex/hooks.json).
• Evidence:

  $ apm compile --target cursor --dry-run
  [i] Compiling for AGENTS.md + CLAUDE.md - explicit --target flag
  
  $ apm compile --target opencode --dry-run
  [i] Compiling for AGENTS.md + CLAUDE.md - explicit --target flag
  
  $ apm compile --target codex --dry-run
  [i] Compiling for AGENTS.md + CLAUDE.md - explicit --target flag
  
  $ apm compile --target all --dry-run
  [i] Compiling for AGENTS.md + CLAUDE.md - explicit --target flag
  ```
  

• Location: src/apm_cli/commands/compile/cli.py, the if/elif/else block around line 390 that builds the progress message. The else comment says # "all" but cursor/opencode/codex also reach it.
• Suggested Fix: Add explicit elif branches for cursor, opencode, and codex (using get_target_description() from target_detection.py which already has correct descriptions), and restrict the final else to only the all case.

---

Medium Severity

1. apm compile docs --target option missing copilot and cursor values

• Location: docs/src/content/docs/reference/cli-commands.md, line 1169
• Problem: The documented valid values for --target are [vscode|agents|claude|codex|opencode|all], but the actual CLI accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all]. The canonical target copilot and the valid target cursor are both absent.
• Evidence:
  • Docs: - \-t, --target [vscode|agents|claude|codex|opencode|all]``
  • CLI help: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
• Suggested Fix: Update the docs option value list to [copilot|claude|cursor|opencode|codex|vscode|agents|all] and note that vscode and agents are deprecated aliases for copilot.

---

2. apm compile docs describe deprecated alias relationship incorrectly

• Location: docs/src/content/docs/reference/cli-commands.md, line 1169
• Problem: The docs say `agents` is an alias for `vscode`, but the CLI help says both vscode and agents are deprecated aliases for copilot. These are contradictory statements, and the docs lead users toward using the deprecated target name.
• Evidence:
  • Docs: Target agent format. \agents` is an alias for `vscode`. Auto-detects if not specified.`
  • CLI help: 'vscode' and 'agents' are deprecated aliases for 'copilot'. Auto-detects if not specified.
• Suggested Fix: Update the docs description to: `copilot` is the canonical target. `vscode` and `agents` are deprecated aliases for `copilot`. `cursor`, `opencode`, `codex` are additional valid targets.

---

3. apm compile docs Auto-Detection table and example YAML use deprecated vscode target without deprecation notice

• Location: docs/src/content/docs/reference/cli-commands.md, lines 1185-1200
• Problem: The Auto-Detection table shows .github/ exists only maps to target vscode. The example YAML shows target: vscode. Both use the deprecated alias without indicating copilot is preferred. This will confuse users who read the docs separately from the CLI help.
• Evidence:

  | .github/ exists only | `vscode` | AGENTS.md + .github/ |
  

  target: vscode  # or claude, codex, opencode, or all
  ```

• Suggested Fix: Replace vscode with copilot in the auto-detection table and example YAML, and add a note: vscode and agents are accepted as deprecated aliases.

---

4. apm compile docs Target Formats table missing copilot and cursor entries

• Location: docs/src/content/docs/reference/cli-commands.md, lines ~1200-1210
• Problem: The Target Formats table lists vscode, claude, codex, opencode, and all — but copilot (the canonical replacement for vscode) and cursor (a valid, distinct target) are absent.
• Evidence: The table has no row for copilot or cursor.
• Suggested Fix: Add a copilot row (replacing or aliasing the vscode row) and a cursor row describing .cursor/agents/, .cursor/skills/, .cursor/rules/.

---

5. apm install docs: --verbose missing short form -v

• Location: docs/src/content/docs/reference/cli-commands.md, line 95
• Problem: The install options list documents --verbose without its -v short form, even though the CLI has -v, --verbose. Every other command that documents verbose uses -v, --verbose in the docs.
• Evidence:
  • Docs: - \--verbose` - Show individual file paths and full error details...`
  • CLI: -v, --verbose Show detailed installation information
• Suggested Fix: Change the docs entry to - \-v, --verbose` - Show individual file paths and full error details in the diagnostic summary`.

---

6. apm deps update docs list verbose flag in wrong order

• Location: docs/src/content/docs/reference/cli-commands.md, line 824
• Problem: The docs format is --verbose, -v (long flag first), while the standard pattern throughout the rest of the docs is -v, --verbose (short flag first). This is inconsistent with all other occurrences.
• Evidence:
  • Docs (deps update): - \--verbose, -v` - Show detailed update information`
  • Docs (all other commands): - \-v, --verbose` - Show detailed output`
• Suggested Fix: Change to - \-v, --verbose` - Show detailed update information`.

---

Low Severity

1. Trailing period in one-line descriptions for outdated and view

• Command: apm outdated, apm view
• Problem: These two commands have trailing periods in their single-line description shown in apm --help and in each command's usage header. All 18 other commands have no trailing period.
• Evidence (from apm --help):

  outdated     Show outdated locked dependencies.
  view         View package metadata or list remote versions.
  

  Compare with: compile Compile APM context into distributed AGENTS.md files (no period)
• Location: First line of docstrings in src/apm_cli/commands/outdated.py:122 and src/apm_cli/commands/view.py:320
• Suggested Fix: Remove the trailing period from both docstrings.

---

2. apm compile internal docstring references outdated target aliases

• Location: src/apm_cli/commands/compile/cli.py, lines ~240-243
• Problem: The command's internal Python docstring (not shown to users via --help) says * vscode/agents: Generates AGENTS.md + .github/ structure (VSCode/GitHub Copilot) without mentioning copilot as the preferred target.
• Evidence:

  * vscode/agents: Generates AGENTS.md + .github/ structure (VSCode/GitHub Copilot)

• Suggested Fix: Update to: * copilot: Generates AGENTS.md + .github/ structure (VSCode/GitHub Copilot). vscode/agents are deprecated aliases.

---

Clean Areas

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

• apm init — Help text, flags, and documentation are consistent.
• apm uninstall — Help text and docs match; --dry-run, -v, --verbose, -g, --global all correctly documented.
• apm update — Simple and consistent.
• apm run / apm preview — Flags -p, --param and -v, --verbose are consistent between CLI and docs.
• apm deps list/tree/info/clean — All consistent between CLI and docs.
• apm deps update — CLI flags are accurate (aside from medium-severity verbose flag ordering in docs).
• apm mcp list/search/show — All consistent; no mcp install subcommand exists or is documented.
• apm config get/set — Behavior (including apm config bare showing full config) matches docs; no config list subcommand exists or is documented.
• apm runtime setup/list/remove/status — All consistent between CLI and docs.
• apm marketplace add/browse/list/remove/update — All consistent.
• apm audit — All flags (--ci, --policy, --no-cache, --no-fail-fast, --strip, --dry-run, -f/--format, -o/--output) are consistent between CLI and docs.
• apm outdated — Flags and docs match (aside from low-severity trailing period).
• apm pack / apm unpack — All flags consistent.
• apm prune — Consistent.
• apm search — Consistent.
• apm view — Consistent (aside from low-severity trailing period).
• apm list — Consistent.
• Error handling — All tested invalid inputs (--nonexistent-flag, missing required args) produce clean, user-friendly error messages with no stack traces.

Generated by CLI Consistency Checker · ◷

• expires on Apr 11, 2026, 1:45 PM UTC