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

[github-actions]

CLI Consistency Report

Date: 2026-05-18
APM Version: 0.12.4 (027c47d)
Commands Inspected: 26

Summary

Severity	Count
High	1
Medium	3
Low	2

---

High Severity

apm runtime setup and apm runtime remove missing windsurf from accepted values

• Command: apm runtime setup, apm runtime remove
• Problem: The CLI help for both commands lists only {copilot|codex|llm|gemini} as valid runtime choices, but commands.md documents windsurf as a valid option. Attempting to pass windsurf shows the restricted choices in the error.
• Evidence:
  • CLI help: Usage: apm runtime setup [OPTIONS] {copilot|codex|llm|gemini}
  • CLI help: Usage: apm runtime remove [OPTIONS] {copilot|codex|llm|gemini}
  • commands.md line: apm runtime setup {copilot|codex|llm|gemini|windsurf} | Install a runtime
  • commands.md line: apm runtime remove {copilot|codex|llm|gemini|windsurf} | Remove an installed runtime
• Suggested Fix: Either add windsurf to the Click choice tuple for both runtime setup and runtime remove, or remove windsurf from commands.md if the runtime is not yet supported.

---

Medium Severity

apm mcp install --help does not expose options as formal CLI options

• Command: apm mcp install
• Problem: The command is documented as an alias for apm install --mcp, but its help text lists options only as a plain-text paragraph in the epilog rather than as structured Click options. Users cannot discover --transport, --url, --env, --header, --registry, --mcp-version, --dev, --dry-run, --force, --verbose, or --no-policy from apm mcp install --help alone.
• Evidence:

  Usage: apm mcp install [OPTIONS] NAME
  
    Add an MCP server to apm.yml. Alias for 'apm install --mcp'.
    ...
  
  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 forward all relevant options from apm install to apm mcp install as proper Click parameters, or clearly state in the description that users must run apm install --mcp NAME ... for full option access.

apm config has no list subcommand

• Command: apm config
• Problem: The config group exposes get, set, and unset, but provides no way to list all current configuration values. apm config get requires a KEY argument and errors without one. Users have no self-service mechanism to inspect the full config state.
• Evidence:

  Commands:
    get    Get a configuration value
    set    Set a configuration value
    unset  Unset a configuration value
  

  Running apm config list produces: Error: No such command 'list'.
  Running apm config get (no args) produces: Error: Missing argument 'KEY'.
• Suggested Fix: Add apm config list (or apm config show) that prints all key/value pairs from the active config file.

Inconsistent description for -y/--yes confirmation flag

• Command: apm runtime remove, apm deps clean
• Problem: The -y/--yes flag is described differently across commands that share the same semantics.
• Evidence:
  • apm runtime remove: -y, --yes Confirm the action without prompting
  • apm deps clean: -y, --yes Skip confirmation prompt
  • apm deps update: (no -y/--yes flag exposed; uses --force instead)
• Suggested Fix: Standardise the description to a single canonical string, e.g. Skip confirmation prompt (matches the majority pattern), and apply it consistently across all commands that take a -y/--yes flag.

---

Low Severity

--all flag on apm compile references a deprecated form in its description

• Command: apm compile
• Problem: The --all flag description says "Equivalent to --target all." but --target all is itself documented as deprecated in the same help text.
• Evidence:

  --all    Compile for all canonical targets. Equivalent to --target all.
  

  And in --target description: Note: '--target all' on 'apm compile' is deprecated; use 'apm compile --all' instead.
• Suggested Fix: Update --all description to avoid referencing the deprecated form, e.g. "Compile for all canonical targets (copilot, claude, cursor, opencode, codex, gemini, windsurf)."

apm update and apm deps update have nearly identical descriptions

• Command: apm update, apm deps update
• Problem: The two commands serve similar purposes but their relationship is undocumented in their own help text, and their descriptions are easily confused.
• Evidence:
  • apm update: "Refresh APM dependencies to the latest matching refs"
  • apm deps update: "Update APM dependencies to latest refs"
  • apm install --update flag: "[deprecated] prefer 'apm update'"
• Suggested Fix: Add a one-line note to apm deps update that clarifies how it differs from apm update, e.g. "Update specific packages (for interactive full-project updates, use 'apm update')."

---

Clean Areas

• Core commands (apm init, apm install, apm uninstall, apm compile, apm run) have comprehensive, well-structured help text with clear option descriptions and deprecation notices.
• apm deps list, apm deps tree, apm deps info, apm deps clean all have sensible, correct help text.
• apm mcp search, apm mcp show, apm mcp list are clean and consistent.
• apm config get and apm config set work as documented.
• apm runtime setup, apm runtime list, apm runtime status all have correct help (modulo the windsurf omission noted above).
• apm audit has detailed, accurate help text covering all documented flags.
• Error handling is solid: missing required arguments and unknown flags produce clear Usage: messages with no stack traces.

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

• expires on May 20, 2026, 2:24 PM UTC