[cli-consistency] CLI Consistency Report — 2026-09-11

[github-actions]

CLI Consistency Report

Date: 2026-09-11
APM Version: 0.30.0 (e38261c)
Commands Inspected: 23 (apm --help plus every subcommand listed in the audit scope, including deps, mcp, config, and runtime subcommand groups)

Summary

Severity	Count
High	0
Medium	2
Low	1

---

Medium Severity

Inconsistent trailing-period style in top-level command summaries (apm --help)

• Command: apm --help
• Problem: The one-line command summaries shown in the top-level Commands: table mix sentences that end with a period and sentences that do not, with no discernible rule (it is not simply "short vs. long" — some short ones have periods and some long ones don't).
• Evidence (exact output from apm --help, full untruncated text via click.testing.CliRunner):

  approve       Approve executable primitives (hooks, MCP, LSP, bin, canvas) for packages.
  audit         Scan installed primitives for hidden Unicode, drift, and lockfile/policy violations
  cache         Manage the local package cache
  compile       Compile APM context into distributed AGENTS.md files
  config        Configure APM CLI.
  deny          Deny executable primitives for packages (a narrowing override).
  deps          Manage APM package dependencies
  doctor        Run environment diagnostics (git, network, auth, marketplace config).
  find          Trace a materialized file back to its contributing package(s).
  init          Initialize a new APM project
  lifecycle     Inspect, test, and scaffold lifecycle scripts.
  list          List available scripts in the current project
  lock          Resolve dependencies and write apm.lock.yaml without deploying or deleting files
  pack          Pack distributable artifacts from your APM project.
  publish       Publish a package to a registry.
  targets       Show resolved targets for the current project.
  unpack        [Deprecated] Extract an APM bundle into the current project.
  update        Refresh APM dependencies to the latest matching refs
  view          View package metadata or list remote versions
  

  Compare config ("Configure APM CLI.") and deny ("...a narrowing override).") which both end with a period, against cache, compile, deps, doctor, find, lock, targets, update, view, which are equally short/complete sentences but have no trailing period.
• Suggested Fix: Pick one convention (Click's own doc style favors no trailing period on short summaries) and apply it uniformly across all @click.command(help=...) / docstring-derived summaries in src/apm_cli/cli.py and the command modules under src/apm_cli/commands/.

Subcommand group help text mixes deprecation notice into the description inconsistently (apm deps update / apm deps --help)

• Command: apm deps --help, apm deps update --help
• Problem: apm deps update's one-line summary in the parent apm deps command table is written as a deprecation notice only ("DEPRECATED: use 'apm update' instead (strict superset)."), while its own --help output states the deprecation notice and then still describes what it does ("...Update APM dependencies to latest refs"). No other deprecated command uses this exact two-part pattern in its parent-listing row — unpack instead prefixes with [Deprecated] in brackets, a different, non-uniform convention for the same concept (deprecation) used only two places in the whole CLI.
• Evidence:

  $ apm deps --help
  Commands:
    ...
    update  DEPRECATED: use 'apm update' instead (strict superset).
    ...
  
  $ apm unpack --help  (as it appears in apm --help)
    unpack        [Deprecated] Extract an APM bundle into the current project.
  
  $ apm deps update --help
  Usage: apm deps update [OPTIONS] [PACKAGES]...
  
    DEPRECATED: use 'apm update' instead (strict superset). Update APM
    dependencies to latest refs
  

• Suggested Fix: Standardize how deprecated commands announce themselves in both the parent listing and their own --help header — pick either the [Deprecated] <description> prefix style (used by unpack) or the DEPRECATED: <reason>. <description> style (used by deps update), and apply it to both commands identically.

---

Low Severity

--target value list presentation differs between CLI help and docs/src/content/docs/reference/cli/deps.md

• Command: apm deps update --help vs. docs/src/content/docs/reference/cli/deps.md
• Problem: The CLI's -t, --target help text for apm deps update lists all target tokens (including experimental ones copilot-app, copilot-cowork, grok-cloud, openclaw) inline in one flat comma list. The docs page instead splits the same option into a "stable" list and a separate parenthetical "Experimental targets (...)" callout. Functionally equivalent, but the two presentations don't match token-for-token, so a reader diffing CLI output against docs may think a token is missing.
• Evidence:

  # CLI (apm deps update --help):
  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.
  
  # docs/src/content/docs/reference/cli/deps.md:
  Values: `agent-skills`, `agents`, `agy`, `all`, `antigravity`, `claude`,
  `codex`, `copilot`, `cursor`, `gemini`, `grok-build`, `hermes`, `intellij`,
  `kiro`, `opencode`, `vscode`, `windsurf`. Experimental targets
  (`copilot-app`, `copilot-cowork`, `grok-cloud`, `openclaw`) are also
  accepted when their feature flags are enabled.
  

• Suggested Fix: No functional bug — purely a cosmetic/readability nit. Optionally add a short note in the docs page next to the CLI-help comparison clarifying that the CLI's flat list intentionally does not visually separate experimental tokens, to preempt confusion during doc-vs-CLI diffing.

---

Clean Areas

• Installation & version check: apm --version and apm --help work correctly from a fresh uv sync install.
• Top-level command inventory: Every command in apm --help (approve, audit, cache, compile, config, deny, deps, doctor, experimental, find, init, install, lifecycle, list, lock, marketplace, mcp, outdated, pack, plugin, policy, preview, prune, publish, run, runtime, search, self-update, targets, uninstall, unpack, update, view) is documented under docs/src/content/docs/reference/cli/ and cross-referenced from docs/src/content/docs/reference/index.md. The README's CLI Reference link (/reference/cli-commands/) correctly redirects via docs/astro.config.mjs to /reference/cli/install/.
• deps, mcp, config, runtime subcommand groups: All subcommands (deps list/tree/info/clean/update/why, mcp list/search/show/install, config get/set/list/unset, runtime list/setup/status/remove) run --help successfully and match their respective docs pages in required arguments, flags, and defaults (e.g., mcp search --limit default 10, mcp list --limit default 20, both matching docs/src/content/docs/reference/cli/mcp.md).
• Flag naming consistency: --verbose/-v, --dry-run, -y/--yes, and -g/--global are spelled identically everywhere they appear across all inspected commands — no --dryrun or other naming drift found.
• Exit behavior on invalid input: 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 produce Click's standard Usage: + Error: messages with exit code 2, no stack traces. apm install --frozen combined with --mcp or positional packages produces a clear, documented error (exit code 1) matching the CLI help text's stated mutual-exclusivity behavior.
• Documentation accuracy spot-checks: apm config resolution-order documentation, APM_POLICY_DISABLE escape hatch (verified present in src/apm_cli/install/phases/policy_gate.py and src/apm_cli/policy/discovery.py), and apm runtime supported runtime list (copilot, codex, llm, gemini) all matched actual CLI behavior and output.

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 · 105.2 AIC · ⌖ 3.62 AIC · ⊞ 9.3K · ◷

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

[github-actions]

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

Closed by Workflow