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

[github-actions]

CLI Consistency Report

Date: 2026-05-19
APM Version: 0.12.4 (14b9a73)
Commands Inspected: 38 (top-level + all subcommands)

Summary

Severity	Count
High	0
Medium	2
Low	1

---

Medium Severity

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

• Commands: apm runtime setup, apm runtime remove
• Problem: Both commands accept {copilot|codex|llm|gemini} as the positional argument enum, but windsurf is omitted. The documentation (packages/apm-guide/.apm/skills/apm-usage/commands.md) lists windsurf as a valid option for both commands. Furthermore, apm targets output shows windsurf as a recognised deployment target (windsurf inactive needs .windsurf/), making this a real gap: users cannot set up or remove the windsurf runtime via the CLI even though it is treated as a first-class target.
• Evidence:
  • CLI: Usage: apm runtime setup [OPTIONS] {copilot|codex|llm|gemini}
  • CLI: Usage: apm runtime remove [OPTIONS] {copilot|codex|llm|gemini}
  • Docs: `apm runtime setup {copilot\|codex\|llm\|gemini\|windsurf}` (commands.md line 127)
  • Docs: `apm runtime remove {copilot\|codex\|llm\|gemini\|windsurf}` (commands.md line 129)
• Suggested Fix: Either add windsurf to the Choice enum in both runtime setup and runtime remove CLI commands, or update the documentation to remove windsurf if runtime management is not yet supported for that target. Given that windsurf is a fully recognised apm targets target, adding it to the enum is the preferred fix.

---

apm targets usage line incorrectly advertises COMMAND [ARGS]...

• Command: apm targets
• Problem: The usage line reads Usage: apm targets [OPTIONS] COMMAND [ARGS]..., which signals a Click command group with subcommands. However, no subcommands are listed in the help output, and the command executes and produces output directly (target table) without requiring a subcommand. The "COMMAND [ARGS]..." fragment is misleading and may confuse users or tooling that parses help text.
• 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 follows -- the group has no registered subcommands.
• Suggested Fix: If apm targets is intended to be a standalone command (no subcommands), change it from a @click.group to a @click.command so the usage line reads Usage: apm targets [OPTIONS]. If subcommands are planned, add a stub or at least ensure the usage line matches the current reality.

---

Low Severity

apm mcp install help options rendered outside standard Options block

• Command: apm mcp install
• Problem: The "Common options" section (listing --transport, --url, --env, etc.) appears after the --help option and is formatted as inline prose rather than as a standard Click Options block. All other commands format their options uniformly in a structured block. This is inconsistent and harder to parse.
• 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: Move the common options summary into the command's help= string (the description paragraph), or better, expose the full option set directly on apm mcp install rather than deferring to apm install --mcp. At minimum, the inline option list should appear above --help, not after it.

---

Clean Areas

The following commands/areas passed all checks (correct usage, accurate docs, sensible errors, consistent flags):

• apm init, apm install, apm uninstall, apm update, apm compile, apm run
• apm deps list, apm deps tree, apm deps info, apm deps clean, apm deps update
• apm mcp search, apm mcp show, apm mcp list
• apm config get, apm config set, apm config unset
• apm runtime list, apm runtime status
• apm audit, apm cache, apm list, apm marketplace (all subcommands), apm outdated
• apm pack, apm policy, apm preview, apm prune, apm search, apm self-update
• apm targets (functionally correct; only the usage-line formatting is flagged)
• apm unpack, apm experimental, apm view
• Error handling: all tested invalid-argument cases (--nonexistent-flag, missing required args) produce clean Error: messages with usage hints -- no stack traces observed.

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

• expires on May 21, 2026, 2:12 PM UTC