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

[github-actions]

CLI Consistency Report

Date: 2026-04-03
APM Version: 0.8.10 (4148963)
Commands Inspected: 38 (top-level + all subcommands; apm mcp install and apm config list were also attempted and confirmed non-existent, matching docs)

Summary

Severity	Count
High	0
Medium	8
Low	3

---

Medium Severity

--target option list incomplete in apm compile docs — deprecated aliases promoted, new values missing

• Command: apm compile
• Problem: The CLI reference documents --target as [vscode|agents|claude|codex|opencode|all]. The actual CLI accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all], where the help text explicitly states 'vscode' and 'agents' are deprecated aliases for 'copilot'. The docs promote the deprecated aliases (vscode, agents) as the canonical options and omit both copilot (the current preferred value) and cursor entirely.
• Evidence:
  • CLI: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all] with note 'vscode' and 'agents' are deprecated aliases for 'copilot'
  • Docs (cli-commands.md line 1091): -t, --target [vscode|agents|claude|codex|opencode|all]
• Suggested Fix: Update the apm compile --target option description to [copilot|claude|cursor|opencode|codex|all] (deprecated aliases can be noted separately), and add cursor as a documented target.

---

--target option list missing vscode and agents in apm install docs

• Command: apm install
• Problem: The CLI reference documents --target for apm install as [copilot|claude|cursor|codex|opencode|all]. The actual CLI accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all]. Users who rely on the vscode/agents aliases (e.g. in CI scripts) won't find them in the docs.
• Evidence:
  • CLI: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  • Docs (cli-commands.md line 90): --target [copilot|claude|cursor|codex|opencode|all]
• Suggested Fix: Add vscode and agents to the documented option list with a note that they are deprecated aliases for copilot.

---

--target option list missing agents in apm pack docs

• Command: apm pack
• Problem: The CLI reference documents --target for apm pack as [copilot|vscode|claude|cursor|codex|opencode|all]. The actual CLI accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all], so agents is missing from the docs.
• Evidence:
  • CLI: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  • Docs (cli-commands.md line 455): -t, --target [copilot|vscode|claude|cursor|codex|opencode|all]
• Suggested Fix: Add agents to the documented target list for apm pack.

---

apm init --verbose flag not documented

• Command: apm init
• Problem: The apm init command supports -v, --verbose (confirmed by apm init --help), but the CLI reference docs do not list it under the command's options.
• Evidence:
  • CLI apm init --help output:

    Options:
      -y, --yes      Skip interactive prompts and use auto-detected defaults
      --plugin       Initialize as plugin author (creates plugin.json + apm.yml)
      -v, --verbose  Show detailed output
      --help         Show this message and exit.
    ```
    

  • Docs (cli-commands.md lines 37-38): only -y, --yes and --plugin listed; no --verbose.
• Suggested Fix: Add -v, --verbose - Show detailed output to the apm init options in the CLI reference.

---

apm deps update --global/-g flag not documented

• Command: apm deps update
• Problem: The apm deps update command supports -g, --global (confirmed by apm deps update --help), but the CLI reference does not list it.
• Evidence:
  • CLI apm deps update --help output includes: -g, --global Update user-scope dependencies (~/.apm/)
  • Docs (cli-commands.md lines 753-757): lists --verbose, -v, --force, --target, -t, --parallel-downloads — no --global.
• Suggested Fix: Add -g, --global - Update user-scope dependencies (~/.apm/) to the apm deps update options.

---

apm deps tree --global/-g flag not documented

• Command: apm deps tree
• Problem: The apm deps tree command supports -g, --global (confirmed by apm deps tree --help), but the CLI reference's options section for this command is empty (no options listed at all).
• Evidence:
  • CLI apm deps tree --help output:

    Options:
      -g, --global  Show user-scope dependency tree (~/.apm/)
      --help        Show this message and exit.
    

  • Docs (cli-commands.md lines 651-663): no Options section; only shows example apm deps tree with no options.
• Suggested Fix: Add an Options section to apm deps tree with -g, --global - Show user-scope dependency tree (~/.apm/).

---

apm config get displays undocumented default_client field

• Command: apm config get
• Problem: Running apm config get (no key) outputs a default_client field that is not mentioned anywhere in the CLI reference docs. Attempting to set it via apm config set default_client vscode fails with [x] Unknown configuration key: 'default_client'. Valid keys: auto-integrate. Users seeing the field in config get output may assume it is settable, which creates confusion.
• Evidence:
  • apm config get output: default_client: vscode
  • apm config set default_client vscode error: [x] Unknown configuration key: 'default_client'. Valid keys: auto-integrate
  • Docs (cli-commands.md lines 1277-1280): only auto-integrate listed as a supported key.
• Suggested Fix: Either document default_client as a read-only display field in the apm config get docs, or suppress it from the output since it cannot be set and may confuse users.

---

--verbose flag undocumented for apm mcp list, apm mcp search, and apm mcp show

• Commands: apm mcp list, apm mcp search, apm mcp show
• Problem: All three commands support -v, --verbose (confirmed by their --help outputs), but none of the CLI reference docs for these commands mention the verbose flag.
• Evidence:
  • apm mcp list --help includes: -v, --verbose Show detailed output
  • apm mcp search --help includes: -v, --verbose Show detailed output
  • apm mcp show --help includes: -v, --verbose Show detailed output
  • Docs for apm mcp list (lines 793-794), apm mcp search (lines 816-817), and apm mcp show (lines 835-848): none list --verbose.
• Suggested Fix: Add -v, --verbose - Show detailed output to the options for all three apm mcp subcommands.

---

Low Severity

apm update docs use emoji in example CLI output (violates ASCII-only rule)

• Command: apm update
• Problem: The CLI reference docs show a version update warning using ⚠️ (a Unicode emoji). The actual source code uses _rich_warning() which outputs [!] (ASCII bracket notation) per the project's cross-platform encoding rule. The docs show incorrect output.
• Evidence:
  • Docs (cli-commands.md line 585-586):

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

  • Source code (src/apm_cli/commands/_helpers.py): uses _rich_warning(f"A new version of APM is available: ...", symbol="warning") which outputs [!].
• Suggested Fix: Replace ⚠️ with [!] in the example output block in the docs.

---

apm install --verbose short flag -v omitted from docs

• Command: apm install
• Problem: The CLI reference lists the verbose flag as --verbose without the short alias. The actual CLI supports -v, --verbose.
• Evidence:
  • CLI apm install --help: -v, --verbose Show detailed installation information
  • Docs (cli-commands.md line 95): --verbose - Show individual file paths and full error details... (no -v short form)
• Suggested Fix: Update to -v, --verbose.

---

apm marketplace add argument name mismatch between docs and CLI

• Command: apm marketplace add
• Problem: The docs describe the required argument as OWNER/REPO, but the CLI help text shows the metavar as REPO.
• Evidence:
  • CLI apm marketplace add --help: Usage: apm marketplace add [OPTIONS] REPO
  • Docs (cli-commands.md line 874): apm marketplace add OWNER/REPO [OPTIONS]
  • Docs argument description (line 877): OWNER/REPO - GitHub repository containing marketplace.json
• Suggested Fix: Align either the CLI metavar to OWNER/REPO (more descriptive for users) or the docs to match REPO, with a note that the format is owner/repo.

---

Clean Areas

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

• apm uninstall — options, help text, and docs all consistent
• apm prune — minimal and accurate
• apm audit — comprehensive and well-documented, including all flags and exit codes
• apm unpack — options and docs match
• apm run and apm preview — consistent between CLI and docs
• apm list — correct
• apm deps list — options and docs match
• apm deps info — options and docs match
• apm deps clean — options and docs match
• apm config set — accurate and consistent
• apm runtime setup, apm runtime list, apm runtime remove, apm runtime status — all match docs
• apm marketplace browse, apm marketplace update, apm marketplace remove, apm marketplace list — all match docs
• apm search — accurate
• Error handling — all tested commands (apm install --nonexistent-flag, apm deps info with missing arg, apm config set with missing args) return clean error messages with no stack traces

Generated by CLI Consistency Checker · ◷

• expires on Apr 5, 2026, 1:34 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-04-05T13:34:16.570Z.

Closed by Workflow