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

[github-actions]

CLI Consistency Report

Date: 2026-05-12
APM Version: 0.12.4 (c212afe)
Commands Inspected: 37

Summary

Severity	Count
High	2
Medium	4
Low	3

---

High Severity

apm update docs describe the wrong command

• Command: apm update
• Problem: The CLI reference docs describe apm update as "Update APM to the latest version" (the CLI binary self-updater), but the actual apm update command refreshes package dependencies (Refresh APM dependencies to the latest matching refs). The binary self-updater is apm self-update. The docs also document --check flag for apm update, which does not exist on apm update (it exists on apm self-update).
• Evidence:
  • docs/src/content/docs/reference/cli-commands.md line 793: ### apm update - Update APM to the latest version
  • docs/src/content/docs/reference/cli-commands.md line 802: - --check - Only check for updates without installing
  • Actual CLI: apm update --help shows Refresh APM dependencies to the latest matching refs with options --yes, --dry-run, --verbose (no --check)
  • Actual CLI: apm self-update --help shows Update the APM CLI binary itself to the latest version with --check flag
• Suggested Fix: Rename the apm update section in docs to document the dependency refresh behavior. Add a new apm self-update section for the binary update command.

apm update --check documented as valid but is deprecated

• Command: apm update --check
• Problem: The docs document apm update --check as a valid way to check for CLI binary updates, but running it produces a deprecation warning and redirects to apm self-update --check. Users following the docs are guided to use a deprecated interface.
• Evidence:
  • docs/src/content/docs/reference/cli-commands.md line 807: apm update --check
  • Actual output: [!] 'apm update --check' is the deprecated self-updater shim. Use 'apm update --dry-run' to preview dependency changes, or 'apm self-update --check' to check for a new CLI binary. Forwarding for back-compat (deprecated).
• Suggested Fix: Remove apm update --check from docs. Replace with apm self-update --check in the documented examples.

---

Medium Severity

apm self-update command has no dedicated documentation section

• Command: apm self-update
• Problem: apm self-update is the command for updating the APM CLI binary itself, with a --check flag. It appears in apm --help and is fully functional, but has no dedicated section in cli-commands.md.
• Evidence:
  • apm self-update --help output: Update the APM CLI binary itself to the latest version with --check flag
  • grep "### .apm self-update" docs/.../cli-commands.md returns no results (only two prose mentions)
• Suggested Fix: Add a ### apm self-update section to cli-commands.md documenting the command, its --check flag, and examples.

apm cache and its subcommands are not documented

• Commands: apm cache, apm cache clean, apm cache info, apm cache prune
• Problem: These commands appear in apm --help and work correctly, but have no documentation in cli-commands.md.
• Evidence:
  • apm cache --help returns: Manage the local package cache with subcommands clean, info, prune
  • grep "apm cache" docs/.../cli-commands.md returns zero results
• Suggested Fix: Add a ### apm cache section documenting the command group and all three subcommands.

apm mcp install --help shows incomplete option listing

• Command: apm mcp install
• Problem: apm mcp install is described as an alias for apm install --mcp, but its --help output only lists --help as a formal option. The other supported flags (--transport, --url, --env, --header, --registry, --mcp-version, --dev, --dry-run, --force, --verbose, --no-policy) are appended as unformatted text at the bottom and are not machine-parseable or tab-completable.
• Evidence:

  Options:
    --help  Show this message and exit.
  
    Common options (see `apm install --mcp --help` for full list): --transport
    [stdio|http|sse|streamable-http] --url URL           Server URL for remote
    transports --env KEY=VALUE     Environment variable (repeatable)...
  

• Suggested Fix: Expose the actual flags as proper Click options on the alias, or at minimum ensure the help text is well-formatted so users understand what flags are available.

apm cache clean has two redundant confirmation-skip flags

• Command: apm cache clean
• Problem: apm cache clean --help shows both -f, --force and -y, --yes described identically as "Skip confirmation prompt". Having two flags with the same effect is confusing.
• Evidence:

  Options:
    -f, --force  Skip confirmation prompt
    -y, --yes    Skip confirmation prompt
    --help       Show this message and exit.
  

• Suggested Fix: Consolidate to one flag (prefer -y/--yes for consistency with apm deps clean and apm update) or differentiate semantics in the description if they have distinct behavior.

---

Low Severity

apm update and apm deps update have nearly identical descriptions

• Commands: apm update, apm deps update
• Problem: Both commands have nearly identical one-line descriptions with no clear distinction, which may cause user confusion about which to use.
• Evidence:
  • apm update description: Refresh APM dependencies to the latest matching refs
  • apm deps update description: Update APM dependencies to latest refs
• Suggested Fix: Differentiate the descriptions to clarify the use case for each (e.g., apm update offers an interactive plan; apm deps update targets specific packages).

Emoji in documentation violates project ASCII encoding rules

• File: docs/src/content/docs/reference/cli-commands.md, line 827
• Problem: The docs show a warning emoji in an example CLI output snippet, but the actual CLI uses [!]. The project ASCII encoding rule prohibits emojis in documentation files.
• Evidence:
  • docs/src/content/docs/reference/cli-commands.md line 827: [warning emoji] A new version of APM is available: 0.7.0 (current: 0.6.3)
  • Actual CLI output: [!] A new version of APM is available: 0.13.0 (current: 0.12.4)
• Suggested Fix: Replace the emoji with [!] to match actual CLI output and comply with the project ASCII encoding convention.

apm deps update lacks -y/--yes flag while apm update has it

• Command: apm deps update
• Problem: apm update supports -y/--yes to skip the confirmation prompt for CI/automation, but apm deps update does not, creating inconsistency between the two related commands.
• Evidence:
  • apm update --help shows: -y, --yes Skip the confirmation prompt (for CI / automation)
  • apm deps update --help shows no -y/--yes flag
• Suggested Fix: Add -y/--yes to apm deps update for CI consistency, or document that it is non-interactive by default.

---

Clean Areas

The following commands/areas passed all checks:

• apm init, apm install, apm uninstall, apm compile -- well-structured, consistent flags
• apm deps list, apm deps tree, apm deps info, apm deps clean -- consistent structure
• apm mcp search, apm mcp show, apm mcp list -- consistent with parent group
• apm config, apm config get, apm config set, apm config unset -- clear and consistent
• apm runtime, apm runtime setup -- appropriately marked experimental
• apm run, apm list, apm preview -- consistent style
• apm audit, apm policy, apm outdated, apm view, apm targets -- thorough help text
• apm experimental -- well-structured with list/enable/disable/reset subcommands
• Error handling: all tested commands produce clean, helpful error messages with no stack traces
• Exit codes: invalid flags and missing required arguments all return exit code 2 with a usage hint

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 · ● 18.5M · ◷

• expires on May 14, 2026, 1:52 PM UTC