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

[github-actions]

CLI Consistency Report

Date: 2026-05-14
APM Version: 0.12.4 (bc8ce83)
Commands Inspected: 47

Summary

Severity	Count
High	0
Medium	3
Low	4

---

Medium Severity

apm cache clean has duplicate confirmation-skip flags

• Command: apm cache clean --help
• Problem: Two flags with identical descriptions both claim to "Skip confirmation prompt": -f, --force and -y, --yes. This is redundant and confusing. The sibling command apm deps clean only exposes -y, --yes for this purpose.
• Evidence:

  Options:
    -f, --force  Skip confirmation prompt
    -y, --yes    Skip confirmation prompt
  

• Suggested Fix: Remove -f, --force from apm cache clean (or change its description to something distinct, e.g. "Force removal without checking cache integrity") to match apm deps clean's single -y, --yes pattern.

---

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

• Command: apm mcp install --help
• Problem: All other commands list their supported options as properly-formatted Click option entries. apm mcp install instead embeds "common options" as raw inline text in the Options section, bypassing Click's standard formatting. This makes the output unreadable and inconsistent with every other command.
• 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
  

• Suggested Fix: Either (a) forward all relevant options through to the Click option list so they appear in standard format, or (b) update the help epilog to use Click's epilog parameter with a clean text block referencing apm install --mcp --help, removing the freeform option dump.

---

apm deps update missing --dry-run flag

• Command: apm deps update --help
• Problem: The top-level apm update (which supersedes apm deps update for interactive use) has a --dry-run flag to render the update plan without executing changes. apm deps update performs similar work but lacks --dry-run, making it impossible to preview non-interactively.
• Evidence:

  # apm update --help:
  Options:
    -y, --yes      Skip the confirmation prompt (for CI / automation)
    --dry-run      Render the update plan and exit without changing anything
    -v, --verbose  ...
  
  # apm deps update --help:
  Options:
    -v, --verbose  Show detailed update information
    --force        Overwrite locally-authored files on collision
    -t, --target   ...
    (no --dry-run)
  

• Suggested Fix: Add --dry-run to apm deps update with the same semantics as apm update --dry-run, or add a note to the help text that directs users to apm update --dry-run for preview functionality.

---

Low Severity

apm targets usage line says COMMAND [ARGS]... but has no subcommands

• Command: apm targets --help
• Problem: The usage line reads apm targets [OPTIONS] COMMAND [ARGS]..., suggesting this is a command group with subcommands. However, no subcommands are listed -- --json and --all are top-level options and apm targets works as a standalone command. The COMMAND [ARGS]... in the usage is misleading.
• 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 subcommands section follows.)
• Suggested Fix: If apm targets has no subcommands, register it as a plain @cli.command() rather than a group, so Click renders Usage: apm targets [OPTIONS] instead.

---

Inconsistent trailing periods in command descriptions

• Problem: Command one-line descriptions have inconsistent use of trailing periods. Some end with a period, others do not. This is visible in apm --help and in each command's own help banner.
• Evidence (with period):
  • apm pack: "Pack distributable artifacts from your APM project."
  • apm mcp install: "Add an MCP server to apm.yml."
  • apm deps clean: "Remove all APM dependencies" (no period)
  • apm cache info: "Show cache location and size statistics" (no period)
  • apm targets: "Show resolved targets for the current project." (has period)
  • apm outdated: "Show outdated locked dependencies" (no period)
• Suggested Fix: Pick one convention (preferably no trailing period, consistent with npm/pip/cargo CLI style) and apply it uniformly to all command short descriptions.

---

apm deps update does not expose --no-policy flag

• Command: apm deps update --help
• Problem: The CLI documentation notes that apm deps update runs the install pipeline and is gated by policy, but unlike apm install it does not expose a --no-policy escape hatch. The only workaround is the environment variable APM_POLICY_DISABLE=1, which is not mentioned in apm deps update --help.
• Evidence: apm install --help includes --no-policy. apm deps update --help has no equivalent and no mention of APM_POLICY_DISABLE=1.
• Suggested Fix: Either add --no-policy to apm deps update to match apm install, or add a note to the apm deps update help text: "To skip policy for this command, set APM_POLICY_DISABLE=1".

---

apm outdated parallel flag is inconsistently named vs apm install

• Command: apm outdated --help
• Problem: apm outdated uses -j, --parallel-checks INTEGER as the flag for concurrency. apm install uses --parallel-downloads INTEGER (no short flag). The parallel-execution flags across these two commands use different long names (--parallel-checks vs --parallel-downloads) and apm outdated adds a -j short form absent everywhere else.
• Evidence:

  # apm outdated:
  -j, --parallel-checks INTEGER  Max concurrent remote checks (default: 4, 0 = sequential)
  
  # apm install:
  --parallel-downloads INTEGER   Max concurrent package downloads (0 to disable parallelism) [default: 4]
  

• Suggested Fix: Align naming to a consistent pattern such as --parallel INTEGER or --jobs INTEGER (-j) across all commands that support concurrency. At minimum, document the inconsistency in a comment so future commands follow one standard.

---

Clean Areas

• All 47 commands responded to --help without crashing or producing stack traces.
• apm install, apm uninstall, apm update, apm compile, apm run, apm init all have well-structured, complete help text.
• apm deps subgroup (list, tree, info, clean) all function correctly with appropriate error messages on missing required args.
• apm mcp search, apm mcp show, apm mcp list are consistent with each other.
• apm config get, apm config set, apm config unset are consistent and well-documented.
• apm runtime subgroup (setup, list, remove, status) all have correct help and accept --help properly.
• Error messages for invalid flags and missing required arguments are clean and actionable (no stack traces).
• Exit behavior on bad input is correct: apm install --nonexistent-flag produces Error: No such option, apm deps info (no PACKAGE) produces Error: Missing argument 'PACKAGE'.
• apm audit options are well-structured and comprehensive.
• apm experimental subgroup is complete and consistent.

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

• expires on May 16, 2026, 1:51 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-05-16T13:51:39.030Z.

Closed by Workflow