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

[github-actions]

CLI Consistency Report

Date: 2026-05-15
APM Version: 0.13.0 (1e02d12)
Commands Inspected: 41 (plus 1 attempted that does not exist: apm config list)

Summary

Severity	Count
High	1
Medium	2
Low	3

---

High Severity

apm targets usage line implies subcommands that do not exist

• Command: apm targets --help
• Problem: The usage line reads Usage: apm targets [OPTIONS] COMMAND [ARGS]..., which is the standard Click pattern for a command group with subcommands. However, no subcommands are listed and none exist. The flags --json and --all are options on the root command itself, not subcommands. This misleads users and tools (shell completions, docs generators) into expecting a apm targets <subcommand> interface that does not exist.
• Evidence:

  Usage: apm targets [OPTIONS] COMMAND [ARGS]...
  
    Show resolved targets for the current project...
  
  Options:
    --json  Output as JSON instead of a table.
    --all   Include the agent-skills meta-target in JSON output...
    --help  Show this message and exit.
  

  No Commands: section appears. Every other command group (apm deps, apm mcp, apm config, apm runtime, etc.) lists its subcommands.
• Suggested Fix: Convert apm targets from a Click group (@click.group) to a plain @click.command so the usage line reads Usage: apm targets [OPTIONS]. All current flags already attach to the root invocation.

---

Medium Severity

apm mcp install --help does not expose its options as proper CLI flags

• Command: apm mcp install --help
• Problem: The apm mcp install subcommand is described as an alias for apm install --mcp, but its --help output embeds the forwarded options as free-form text rather than as real Click options. This breaks flag discovery, shell tab-completion, and the standard --help contract. The embedded text also has inconsistent formatting (line breaks mid-option).
• 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) --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
  

  All other commands (apm install, apm compile, apm update, etc.) list their flags as proper Click options.
• Suggested Fix: Either (a) declare the forwarded options as real Click parameters on apm mcp install so they appear in help properly, or (b) if full forwarding is architecturally complex, at minimum move the "Common options" text into the command's help= docstring so it renders before the Options: block and the formatting is controlled.

apm config list does not exist, breaking the pattern of every other APM command group

• Command: apm config list --help
• Problem: Every other APM command group that wraps read operations exposes a list subcommand (apm deps list, apm mcp list, apm marketplace list, apm experimental list, apm cache subcommands). apm config does not, requiring users to know that apm config get with no argument prints all keys. This breaks the discoverability pattern.
• Evidence:

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

  apm config --help shows only get, set, unset. apm deps --help, apm mcp --help, apm experimental --help all show a list subcommand.
• Suggested Fix: Add apm config list as an alias for apm config get (no arguments) so that apm config list prints all configuration keys and values, consistent with the rest of the CLI.

---

Low Severity

Trailing period inconsistency in short command descriptions

• Commands: apm pack, apm unpack
• Problem: The short description shown in apm --help ends with a period for pack and unpack, but no other command does.
• Evidence:

  pack          Pack distributable artifacts from your APM project.
  unpack        [Deprecated] Extract an APM bundle into the current project.
  install       Install APM and MCP dependencies (supports APM packages,...
  compile       Compile APM context into distributed AGENTS.md files
  update        Refresh APM dependencies to the latest matching refs
  

• Suggested Fix: Remove trailing periods from apm pack and apm unpack short descriptions to match all other commands.

apm prune missing --verbose flag present in comparable removal commands

• Command: apm prune --help
• Problem: apm prune removes packages not listed in apm.yml, but its --help shows only --dry-run and --help. The closely related apm uninstall command offers -v, --verbose for detailed removal information. Users expect consistent verbosity control across removal-type commands.
• Evidence:

  # apm prune --help
  Options:
    --dry-run  Show what would be removed without removing
    --help     Show this message and exit.
  
  # apm uninstall --help
  Options:
    --dry-run      Show what would be removed without removing
    -v, --verbose  Show detailed removal information
    ...
  

• Suggested Fix: Add -v, --verbose to apm prune with the description "Show detailed removal information", consistent with apm uninstall.

apm deps list, apm deps tree, and apm deps info lack --verbose flag

• Commands: apm deps list --help, apm deps tree --help, apm deps info --help
• Problem: apm deps update --help offers -v, --verbose, but the read-only inspection subcommands (list, tree, info) do not. Other read-only commands in the CLI (apm mcp search, apm mcp show, apm outdated) expose --verbose for additional detail. This creates an inconsistent experience within the apm deps group.
• Evidence: None of apm deps list --help, apm deps tree --help, or apm deps info --help include a --verbose option.
• Suggested Fix: Add -v, --verbose to apm deps list, apm deps tree, and apm deps info to expose additional diagnostic detail (e.g., resolved source URLs, primitive counts breakdown, git ref status).

---

Clean Areas

The following commands and areas passed all checks:

• apm init, apm install, apm uninstall, apm update, apm compile, apm run -- flags, descriptions, and examples are clear and consistent.
• apm deps clean, apm deps update -- properly document --dry-run, --yes, and --force.
• apm mcp search, apm mcp show, apm mcp list -- consistent --limit and --verbose flags; defaults match documentation.
• apm config get, apm config set, apm config unset -- accurate flag descriptions; docs match CLI.
• apm runtime setup, apm runtime list, apm runtime status, apm runtime remove -- consistent and well-described.
• apm audit -- comprehensive flags, clear descriptions, exit code documentation.
• apm pack, apm cache, apm experimental, apm marketplace, apm policy, apm search, apm self-update, apm outdated, apm view, apm preview, apm prune (except missing --verbose), apm unpack (deprecated notice present).
• Error handling: all tested invalid invocations (--nonexistent-flag, missing required arguments) produce clean Error: messages with usage hints -- no stack traces observed.
• Exit behavior is consistent and sensible across all tested commands.

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

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