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

[github-actions]

CLI Consistency Report

Date: 2026-05-08
APM Version: Agent Package Manager (APM) CLI version 0.12.4 (73f0e9c)
Commands Inspected: 38

Summary

Severity	Count
High	0
Medium	5
Low	3

---

Medium Severity

M1: apm install --runtime omits windsurf from valid values

• Command: apm install --help
• Problem: The CLI help text for --runtime does not list windsurf as a valid runtime, but the documentation explicitly includes it.
• Evidence (CLI):

  --runtime TEXT  Target specific runtime only (copilot, codex, vscode, cursor, opencode, gemini, claude)
  

• Evidence (docs line 91):

  --runtime TEXT - Target specific runtime only (copilot, codex, vscode, cursor, opencode, gemini, claude,windsurf)
  

• Suggested Fix: Add windsurf to the --runtime help text in the CLI source, or remove it from the docs if windsurf is not a supported runtime target.

---

M2: apm deps tree --global option is undocumented

• Command: apm deps tree --help
• Problem: The CLI exposes a -g, --global flag on apm deps tree, but the documentation has no Options section for this command and does not mention the flag.
• Evidence (CLI):

  Options:
    -g, --global  Show user-scope dependency tree (~/.apm/)
    --help        Show this message and exit.
  

• Evidence (docs, lines 999-1008): The apm deps tree section shows only an example with no options documented.
• Suggested Fix: Add the --global option to the apm deps tree section in docs/src/content/docs/reference/cli-commands.md.

---

M3: apm deps update --target CLI help omits windsurf

• Command: apm deps update --help
• Problem: The CLI help for apm deps update --target lists 8 targets but omits windsurf, while the documentation includes it.
• Evidence (CLI):

  -t, --target TARGET  Target platform (comma-separated). Values:
                       copilot, claude, cursor, opencode, codex,
                       gemini, agent-skills, all.
  

• Evidence (docs line 1097):

  Valid values: copilot, claude, cursor, opencode, codex, gemini, windsurf, agent-skills, vscode, agents (deprecated), all.
  

• Suggested Fix: Add windsurf to the --target values list in the apm deps update help text.

---

M4: apm pack --target docs list deprecated vscode and omit agent-skills

• Command: apm pack --help
• Problem: The documentation lists vscode (a deprecated alias) as a valid --target value for apm pack, and omits agent-skills which is valid per the CLI. The bundle target filtering table in the docs also uses the deprecated vscode label.
• Evidence (CLI):

  -t, --target TARGET  Target platform (comma-separated). Values:
                       copilot, claude, cursor, opencode, codex, gemini,
                       windsurf, agent-skills, all.
  

• Evidence (docs line 674):

  -t, --target [copilot|vscode|claude|cursor|codex|opencode|gemini|windsurf|all]
  

• Evidence (docs bundle table, ~line 725):

  | vscode | .github/ |
  

• Suggested Fix: Replace vscode with copilot in the docs target list and bundle table. Add agent-skills to the apm pack --target documented values.

---

M5: apm mcp install --help uses non-standard help format

• Command: apm mcp install --help
• Problem: Unlike all other commands which list options as structured Click options, apm mcp install only shows --help as a formal option. The actual supported flags (--transport, --url, --env, --header, --registry, --mcp-version, --dev, --dry-run, --force, --verbose, --no-policy) appear as free-form text in the epilog, not as proper CLI options. This breaks consistency and prevents --help from being machine-parseable for this command.
• Evidence (CLI):

  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) ...
  

• Suggested Fix: Register the forwarded flags as proper Click options on the apm mcp install command, or at minimum improve the epilog formatting so it renders as a clean multi-line section.

---

Low Severity

L1: apm init missing --target and --verbose options in documentation

• Command: apm init --help
• Problem: The CLI exposes --target TARGET and -v, --verbose on apm init, but both are absent from the documentation.
• Evidence (CLI):

  Options:
    -y, --yes        Skip interactive prompts and use auto-detected defaults
    --plugin         Initialize as plugin author (creates plugin.json + apm.yml)
    --marketplace    Seed apm.yml with a 'marketplace:' authoring block
    --target TARGET  Comma-separated target list (skip prompt, write directly)
    -v, --verbose    Show detailed output
    --help           Show this message and exit.
  

• Evidence (docs, lines 37-39): Only -y/--yes, --plugin, and --marketplace are listed.
• Suggested Fix: Add --target TARGET and -v, --verbose to the apm init Options section in docs/src/content/docs/reference/cli-commands.md.

---

L2: Emoji in apm update version notification example violates ASCII-only encoding rule

• Command: docs for apm update
• Problem: The documentation example for the auto-update notification (line 829) contains the [!] emoji character (U+26A0 + U+FE0F), violating the project encoding rule that restricts all source/docs to printable ASCII (U+0020-U+007E).
• Evidence (docs line 829):

  [warning-emoji]  A new version of APM is available: 0.7.0 (current: 0.6.3)
  

  (actual content uses the Unicode warning sign + variation selector)
• Suggested Fix: Replace with the ASCII-safe equivalent: [!] A new version of APM is available: 0.7.0 (current: 0.6.3) per the STATUS_SYMBOLS convention.

---

L3: Bundle target filtering table in apm pack docs uses deprecated vscode label

• Command: docs for apm pack
• Problem: The "Bundle target filtering" table in the apm pack documentation uses the deprecated vscode target name as a row key instead of the current canonical name copilot.
• Evidence (docs, ~line 725):

  | Target | Includes paths starting with |
  |--------|------------------------------|
  | `vscode` | `.github/` |
  

• Suggested Fix: Update the table row from `vscode` to `copilot` (optionally adding a note that the vscode alias is still accepted).

---

Clean Areas

The following commands and areas passed all consistency checks:

• apm --help / apm --version - correct, complete
• apm install - comprehensive help with accurate descriptions
• apm uninstall - consistent with docs
• apm compile - consistent; --all / --target all deprecation noted correctly
• apm run / apm preview - consistent with docs
• apm deps list / apm deps info / apm deps clean - consistent with docs
• apm mcp search / apm mcp show / apm mcp list - consistent with docs
• apm config get / apm config set / apm config unset - consistent with docs (config list does not exist in CLI or docs -- both are correct)
• apm runtime setup / apm runtime list - consistent with docs
• apm audit - thorough and accurate
• apm outdated - consistent
• apm prune - consistent
• apm search - consistent
• apm targets - consistent
• apm view - consistent
• apm marketplace (all subcommands) - consistent with docs
• apm experimental - consistent
• apm unpack - deprecation notice present and consistent
• apm policy status - consistent
• Error messages for invalid flags and missing required arguments are clean (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 · ● 3.6M · ◷

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