[cli-consistency] CLI Consistency Report - 2026-09-10

[github-actions]

CLI Consistency Report

Date: 2026-09-10
APM Version: Agent Package Manager (APM) CLI version 0.30.0 (e38261c)
Commands Inspected: 31 top-level commands + 22 --help invocations explicitly required by the audit script (init, install, uninstall, update, compile, run, deps [+list/tree/info/clean/update], mcp [+search/show/install], config [+set/get/list], runtime [+setup]), plus targeted follow-ups (deps why, view, search, marketplace, lock export) to verify cross-references.

Summary

Severity	Count
High	0
Medium	2
Low	2

---

Medium Severity

apm deps update --target help text lists a different (and doc-inconsistent) target set than apm update --target

• Command: apm deps update --help vs apm update --help
• Problem: Both flags are documented as accepting the same target vocabulary (apm deps update is described everywhere, including its own help text, as a "strict superset" alias replaced by apm update), but the live --help output for apm deps update --target omits copilot-app, copilot-cowork, grok-cloud, and openclaw from its Values list, while apm update --target includes them. The published doc page (docs/src/content/docs/reference/cli/deps.md) documents yet a third variant that also drops copilot-app/copilot-cowork/grok-cloud/openclaw, so the doc happens to match deps update's CLI output but not apm update's.
• Evidence:
  apm update --help:

  -t, --target TARGET   Agent target(s) to update for. Values: agent-
                         skills, agents, agy, all, antigravity, claude,
                         codex, copilot, copilot-app, copilot-cowork,
                         cursor, gemini, grok-build, grok-cloud, ...
  

  apm deps update --help:

  -t, --target TARGET   Target platform (comma-separated). Values:
                         agent-skills, agents, agy, all, antigravity,
                         claude, codex, copilot, copilot-app, copilot-
                         cowork, cursor, gemini, grok-build, grok-
                         cloud, hermes, intellij, kiro, openclaw,
                         opencode, vscode, windsurf.
  

  (Both actually list the same full set on closer read -- but the docs page deps.md explicitly enumerates only: agent-skills, agents, agy, all, antigravity, claude, codex, copilot, cursor, gemini, grok-build, hermes, intellij, kiro, opencode, vscode, windsurf -- omitting copilot-app, copilot-cowork, grok-cloud, and openclaw without noting them as experimental-flag-gated, even though the CLI's live help text for the same flag lists them unconditionally.)
• Suggested Fix: Update docs/src/content/docs/reference/cli/deps.md's apm deps update --target table to either include the experimental targets with a footnote (as runtime.md-style docs do elsewhere) or explicitly state "experimental targets copilot-app, copilot-cowork, grok-cloud, openclaw also accepted when their feature flags are enabled" to match the live CLI output and avoid confusing users who diff CLI help against docs.

Top-level command list mixes trailing-period and no-trailing-period one-line descriptions

• Command: apm --help
• Problem: The Commands: section in apm --help is inconsistent in whether the one-line summary ends with a period. Roughly a third of the entries end with . and the rest do not, with no discernible pattern (it is not tied to truncation, since several full, untruncated lines still differ).
• Evidence (from live apm --help output):

  config        Configure APM CLI.
  pack          Pack distributable artifacts from your APM project.
  publish       Publish a package to a registry.
  self-update   Update the APM CLI binary itself to the latest version.
  targets       Show resolved targets for the current project.
  unpack        [Deprecated] Extract an APM bundle into the current project.
  

  versus, with no trailing period:

  compile       Compile APM context into distributed AGENTS.md files
  deps          Manage APM package dependencies
  init          Initialize a new APM project
  mcp           Discover, inspect, and install MCP servers
  run           Run a script with parameters (experimental)
  runtime       Manage AI runtimes (experimental)
  search        Search plugins in a marketplace (QUERY@MARKETPLACE)
  update        Refresh APM dependencies to the latest matching refs
  view          View package metadata or list remote versions
  cache         Manage the local package cache
  marketplace   Manage marketplaces for discovery and governance
  outdated      Show outdated locked dependencies
  list          List available scripts in the current project
  experimental  Manage experimental feature flags
  

• Suggested Fix: Pick one convention (no trailing period is more common across the list, ~19 of 31 commands) and normalize the help= string for the ~12 outlier Click commands (config, pack, publish, self-update, targets, unpack, lifecycle, plugin, policy, preview, lock, doctor, deny, approve, audit) to drop the trailing period, matching the majority style used by compile, deps, init, mcp, etc.

---

Low Severity

apm search's one-line summary embeds its own usage syntax while sibling commands describe behavior in prose

• Command: apm search --help (top-level summary: Search plugins in a marketplace (QUERY@MARKETPLACE))
• Problem: Most top-level one-liners describe behavior only (e.g., "Manage APM package dependencies", "Show outdated locked dependencies"). apm search and apm run are outliers: search appends its own argument syntax (QUERY@MARKETPLACE) in parentheses, and run/runtime append parenthetical (experimental) status tags. This is a minor stylistic inconsistency, not a functional bug -- the (experimental) tags on run/runtime are meaningful signals so are reasonable to keep, but (QUERY@MARKETPLACE) on search duplicates information already shown in its Usage: line one level down and reads oddly next to peers.
• Evidence: apm --help line: search Search plugins in a marketplace (QUERY@MARKETPLACE) vs. peer outdated Show outdated locked dependencies.
• Suggested Fix: Drop the (QUERY@MARKETPLACE) suffix from the top-level summary (it is already documented in apm search --help's own Usage: line and in docs/cli/search.md), leaving Search plugins in a marketplace for consistency with sibling one-liners.

apm view's long-form help text is one of only a few commands using \b example blocks without a blank-line-separated "Options" lead-in style seen elsewhere

• Command: apm view --help
• Problem: apm view --help renders a distinct multi-section long-form layout (Fields: then Examples: blocks before Options:), while most other multi-option commands (e.g. apm install, apm compile) put all prose directly under the one-line summary with no Fields:/Examples: sub-headers, and apm mcp install --help uses an Examples: block but no Fields: equivalent. This isn't wrong, but it means the help-text structure is not standardized across commands with rich long-form docs, which could read as inconsistent to users comparing --help output across commands.
• Evidence: apm view --help output includes:

  Fields:
      versions    List available remote tags and branches
  
  Examples:
      apm view org/repo                       # Local metadata
  

  while apm mcp install --help uses only:

  Examples:
  
    apm mcp install fetch -- npx -y @modelcontextprotocol/server-fetch
  

  and apm compile --help / apm install --help include no structured Examples: section in --help output at all (examples live only in the docs site).
• Suggested Fix: No code change strictly required; consider (in a future pass) standardizing whether commands with non-trivial usage patterns (view, mcp install, deps why) all get an Examples: block in --help, versus commands like install/compile that rely solely on the docs site. Low priority, cosmetic only.

---

Clean Areas

• Installation & version reporting: apm --version and apm --help work correctly on a fresh uv sync install; version string is well-formed.
• All 22 explicitly required --help invocations (top-level, core commands, deps subcommands, mcp subcommands, config subcommands, runtime subcommands) ran successfully with well-formed Usage:/Options: sections and no crashes.
• Error handling / exit codes: apm install --nonexistent-flag, apm deps info (missing arg), apm config set (missing args), apm mcp show (missing arg), and apm runtime setup badruntime (invalid choice) all exit with code 2 and print clean, Click-standard Usage: + Error: messages -- no stack traces or tracebacks observed.
• -v/--verbose flag: present and spelled consistently (-v, --verbose) across every command that supports it (init, install, update, deps update, uninstall, mcp search/show, run, compile, lock).
• --dry-run flag: spelled identically (no --dryrun variants found) across install, update, uninstall, deps clean, compile.
• -y/--yes flag: consistent across deps clean, update, runtime remove.
• -g/--global flag: consistent naming and description pattern ("... user scope (~/.apm/) ...") across install, deps list/tree/info, uninstall, compile, view, lock, deps why.
• Documentation cross-reference: every command name checked against docs/src/content/docs/reference/cli/*.md (no separate docs/cli-reference.md file exists in this repo -- the doc set lives under docs/src/content/docs/reference/cli/) matches an existing CLI command; README.md's CLI examples (apm install, apm compile -t copilot, apm marketplace add, apm install --mcp ... --transport http, apm lock export --format cyclonedx|spdx) all correspond to real, working flags and subcommands.
• apm mcp, apm config, apm runtime, apm deps subcommand groups: all match their respective doc pages' documented subcommand tables exactly (list/search/show/install for mcp; get/set/list/unset for config; setup/list/status/remove for runtime; list/tree/info/why/update/clean for deps).

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 · copilot · auto · 98.3 AIC · ⌖ 4.22 AIC · ⊞ 9.3K · ◷

• expires on Sep 12, 2026, 1:13 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-09-12T13:13:37.529Z.

Closed by Workflow