[cli-consistency] CLI Consistency Report -- 2026-05-13

[github-actions]

CLI Consistency Report

Date: 2026-05-13
APM Version: 0.12.4 (b0cfea4)
Commands Inspected: 34 (all top-level commands + subcommands)

Summary

Severity	Count
High	2
Medium	3
Low	1

---

High Severity

apm update documentation describes the wrong command

• Command: apm update
• Problem: The CLI reference docs describe apm update as "Update APM CLI to the latest version" -- the command that fetches the latest CLI binary from GitHub releases. In reality, apm update refreshes package dependencies, while apm self-update updates the CLI binary. The docs section is titled incorrectly and describes the wrong behavior and options.
• Evidence (docs, cli-commands.md lines 793-846):

  ### `apm update` - Update APM to the latest version
  Update the APM CLI to the latest version available on GitHub releases.
  Options:
  - `--check` - Only check for updates without installing
  

• Evidence (actual CLI):

  $ apm update --help
  Usage: apm update [OPTIONS]
    Refresh APM dependencies to the latest matching refs
  Options:
    -y, --yes      Skip the confirmation prompt (for CI / automation)
    --dry-run      Render the update plan and exit without changing anything
    -v, --verbose  Show unchanged deps and detailed pipeline diagnostics
  
  $ apm self-update --help
  Usage: apm self-update [OPTIONS]
    Update the APM CLI binary itself to the latest version
  Options:
    --check  Only check for updates without installing
  

• Suggested Fix: Rename the docs section to ### \apm self-update` - Update the APM CLI binaryand update all content/examples to reflect the actualapm self-updatecommand. Add a separate section documentingapm update(dependency refresh) with its actual flags:--yes, --dry-run, --verbose. Remove the --checkoption from theapm updatesection (it belongs toapm self-update`).

---

apm config list subcommand does not exist

• Command: apm config list
• Problem: The apm config group has no list subcommand. Users or documentation that references apm config list will encounter an error.
• Evidence:

  $ apm config list
  Usage: apm config [OPTIONS] COMMAND [ARGS]...
  Try 'apm config --help' for help.
  Error: No such command 'list'.
  

  The apm config --help shows only: get, set, unset.
• Suggested Fix: Either (a) add an apm config list subcommand as an alias for apm config get (no args) that prints all config values, or (b) document the absence clearly so users know to use apm config get (without arguments) to list all settings.

---

Medium Severity

apm init missing --target and --verbose flags in documentation

• Command: apm init
• Problem: The docs (cli-commands.md lines 36-39) list only -y/--yes, --plugin, and --marketplace under Options, missing two flags present in the actual CLI.
• Evidence (actual CLI):

  $ apm init --help
  Options:
    -y, --yes        Skip interactive prompts and use auto-detected defaults
    --plugin         Initialize as plugin author (creates plugin.json + apm.yml)
    --marketplace    Seed apm.yml with a 'marketplace:' authoring block
    --target TARGET  Comma-separated target list (skip prompt, write directly)
    -v, --verbose    Show detailed output
  

• Suggested Fix: Add --target TARGET and -v, --verbose to the apm init options table in the docs with appropriate descriptions.

---

apm mcp list missing --verbose flag in documentation

• Command: apm mcp list
• Problem: The docs (cli-commands.md lines 1174-1175) only list --limit INTEGER for apm mcp list, omitting the -v, --verbose flag that is present in the actual CLI.
• Evidence (actual CLI):

  $ apm mcp list --help
  Options:
    --limit INTEGER  Number of results to show  [default: 20]
    -v, --verbose    Show detailed output
  

• Suggested Fix: Add - \-v, --verbose` - Show detailed outputto theapm mcp list` options list in the docs.

---

apm install docs have a formatting typo in --runtime description

• Command: apm install
• Problem: The docs (cli-commands.md line 91) for the --runtime TEXT option are missing a space before windsurf in the accepted values list.
• Evidence (docs):

  - `--runtime TEXT` - Target specific runtime only (copilot, codex, vscode, cursor, opencode, gemini, claude,windsurf)
  

  Note the claude,windsurf with no space.
• Suggested Fix: Change claude,windsurf to claude, windsurf for consistent formatting.

---

Low Severity

apm update docs use emoji in version warning example

• Command: apm update (documentation)
• Problem: The cli-commands.md docs include an emoji character in the version-nag example output (line 828), which violates the project's ASCII-only encoding policy for documentation.
• Evidence (docs, line 828):

  ⚠️  A new version of APM is available: 0.7.0 (current: 0.6.3)
  

  The actual CLI outputs [!] (ASCII bracket notation per STATUS_SYMBOLS), not ⚠️.
• Suggested Fix: Replace ⚠️ with [!] in the docs example to match actual CLI output and comply with the encoding rules.

---

Clean Areas

The following commands/areas passed all checks with no inconsistencies:

• apm --help (top-level): correct command listing, accurate descriptions
• apm install --help: comprehensive, accurate, all flags documented
• apm uninstall --help: accurate, consistent with docs
• apm compile --help: accurate, --all deprecation note matches docs
• apm run --help: accurate (experimental label present in both CLI and docs)
• apm deps list/tree/info/clean --help: accurate and consistent
• apm deps update --help: accurate
• apm mcp search/show/install --help: accurate (install alias pattern is clear)
• apm config get/set --help: accurate and consistent with docs
• apm runtime --help and apm runtime setup --help: accurate
• apm audit --help: accurate and comprehensive
• apm outdated --help: accurate
• apm pack --help: accurate
• apm experimental --help: accurate
• apm marketplace --help: accurate
• Error handling: all tested invalid-argument cases produce clean error messages with no stack traces (exit code 2)

Warning

Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

• astral.sh
• index.crates.io

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "astral.sh"
    - "index.crates.io"

See Network Configuration for more information.

Generated by CLI Consistency Checker · ● 18M · ◷

• expires on May 15, 2026, 1:59 PM UTC