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

[github-actions]

CLI Consistency Report

Date: 2026-05-15
APM Version: 0.12.4 (027c47d)
Commands Inspected: 43

Summary

Severity	Count
High	0
Medium	3
Low	2

---

Medium Severity

apm cache clean has two conflicting confirmation-skip flags

• Command: apm cache clean
• Problem: Two flags both described as "Skip confirmation prompt" exist on the same command: -f, --force and -y, --yes. This is redundant, inconsistent with the rest of the CLI (which standardizes on -y, --yes for confirmation skipping -- e.g. apm deps clean, apm runtime remove, apm deps update ... -y), and confusing because --force means "overwrite on collision" in every other context (e.g. apm install --force, apm deps update --force).
• Evidence:

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

• Suggested Fix: Remove -f, --force from apm cache clean. Keep -y, --yes only, consistent with apm deps clean and other destructive commands. If --force has a separate semantic meaning (e.g., force even on cache inconsistency), update its description to clarify that.

---

apm mcp install --help uses non-standard free-text options format

• Command: apm mcp install
• Problem: The options section renders as an unstructured paragraph rather than the standard Click option-per-line format used by every other command. This makes it harder to scan and breaks the visual consistency of the CLI.
• Evidence:

$ apm mcp install --help
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) --header
  KEY=VALUE  HTTP header (repeatable) --registry URL      Custom registry URL
  --mcp-version VER    Pin registry entry to a specific version --dev / --dry-
  run / --force / --verbose / --no-policy

Compare to standard format from apm mcp search:

Options:
  --limit INTEGER  Number of results to show  [default: 10]
  -v, --verbose    Show detailed output
  --help           Show this message and exit.

• Suggested Fix: Either (a) forward all apm install --mcp options into apm mcp install so they appear in standard Click format, or (b) replace the free-text block with a clean epilog note such as: Run 'apm install --mcp --help' for the full option list.

---

apm targets Usage line implies subcommands that do not exist

• Command: apm targets
• Problem: The Usage line shows apm targets [OPTIONS] COMMAND [ARGS]... which implies subcommands are available. However there are no subcommands -- the command runs as a standalone table display. Users who attempt apm targets list or similar receive Error: No such command 'list'.
• Evidence:

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

• Suggested Fix: Change the command from a Click group (which always shows COMMAND [ARGS]...) to a regular Click command with invoke_without_command=True removed, or add the expected subcommands. If keeping as a group for forward-compatibility, update the help text to note that no subcommands exist yet.

---

Low Severity

Inconsistent punctuation in --verbose flag descriptions

• Commands: apm pack, and others
• Problem: Most verbose descriptions omit a trailing period (Show detailed output) but apm pack includes one (Show detailed packing information.). Minor but inconsistent across the 13+ commands that expose -v, --verbose.
• Evidence:
  • apm install -v: Show detailed installation information (no period)
  • apm pack -v: Show detailed packing information. (has period)
  • apm update -v: Show unchanged deps and detailed pipeline diagnostics (no period)
• Suggested Fix: Remove the trailing period from apm pack's verbose description to match the rest.

---

apm update --yes parenthetical annotation is inconsistent

• Command: apm update
• Problem: The -y, --yes description includes an informal parenthetical (for CI / automation) which no other command uses. All other commands with --yes give a plain description.
• Evidence:

$ apm update --help
  -y, --yes      Skip the confirmation prompt (for CI / automation)

Compare to:

$ apm deps clean --help
  -y, --yes  Skip confirmation prompt

$ apm runtime remove --help
  -y, --yes  Confirm the action without prompting

• Suggested Fix: Simplify to Skip the confirmation prompt to match the style of sibling commands.

---

Clean Areas

• Error handling: All tested invalid-argument scenarios (--nonexistent-flag, missing required args) produce clean Error: messages -- no stack traces or unhandled exceptions observed.
• --help / -h flags: Both work on every command and subcommand tested.
• Core commands (apm init, apm install, apm uninstall, apm update, apm compile, apm run): Help text is complete, well-structured, and accurate.
• apm deps subcommands: Consistent structure and option naming across list, tree, info, clean, update.
• apm runtime subcommands: Consistent structure across setup, list, remove, status.
• apm config subcommands: get, set, unset are clean; bare apm config correctly displays a configuration table.
• apm audit: Comprehensive help text with all flags documented accurately.
• apm pack: Detailed help text with examples and exit codes documented.
• Documentation cross-reference (packages/apm-guide/.apm/skills/apm-usage/commands.md): Commands documented there (apm config, apm config get/set/unset, core commands) all exist and behave as described. No phantom commands found in docs.
• --dry-run consistency: Present and consistently described on all commands where applicable (apm install, apm uninstall, apm compile, apm deps clean, apm cache clean, apm pack, apm prune, apm audit).

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• astral.sh

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

network:
  allowed:
    - defaults
    - "astral.sh"

See Network Configuration for more information.

Generated by CLI Consistency Checker · ● 11.1M · ◷

• expires on May 17, 2026, 1:44 PM UTC