[cli-consistency] CLI Consistency Report -- 2026-06-11

[github-actions]

CLI Consistency Report

Date: 2026-06-11
APM Version: 0.19.0 (cb9fb93)
Commands Inspected: 27

All commands were run directly via the installed apm CLI. Every finding below is backed by exact command output.

Summary

Severity	Count
High	0
Medium	3
Low	2

---

High Severity

None found.

---

Medium Severity

1. apm mcp install --help surfaces forwarded options as unstructured epilog text

• Command: apm mcp install --help
• Problem: The formal Options: block shows only --help. The options that are actually accepted (--transport, --url, --env, --header, --registry, --mcp-version, --dev, --dry-run, --force, --verbose, --no-policy) appear only as free-form text in an epilog paragraph. Users who rely on --help to discover options cannot see their types, defaults, or descriptions. The options do work at runtime (they are forwarded to apm install --mcp), but they are undiscoverable through the standard help interface.
• Evidence:

$ apm mcp install --help
Usage: apm mcp install [OPTIONS] NAME

  Add an MCP server to apm.yml. Alias for 'apm install --mcp'.

  Examples:
    apm mcp install fetch -- npx -y `@modelcontextprotocol/server-fetch`
    apm mcp install api --transport http --url (example.com/redacted)

Options:
  --help  Show this message and exit.

  Common options (see `apm install --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: Declare the forwarded options explicitly as Click parameters on apm mcp install (or use a shared option group / decorator), so they appear as properly formatted entries in the Options: block with their types and descriptions.

---

2. apm uninstall lacks -y/--yes for non-interactive / CI use

• Command: apm uninstall
• Problem: apm uninstall removes packages, their deployed files, and apm.yml entries -- a destructive, irreversible operation -- yet it exposes no --yes flag to skip a confirmation prompt in CI or scripting contexts. By contrast, apm update (-y, --yes) and apm deps clean (-y, --yes) both have this flag. Without --yes, scripts that need to remove a package non-interactively must pipe y or use workarounds.
• Evidence:

$ apm uninstall --help
Usage: apm uninstall [OPTIONS] PACKAGES...

  Remove APM packages, their integrated files, and apm.yml entries

Options:
  --dry-run      Show what would be removed without removing
  -v, --verbose  Show detailed removal information
  -g, --global   Remove from user scope (~/.apm/) instead of the current project
  --help         Show this message and exit.

Compare apm update --help:

  -y, --yes   Skip the confirmation prompt (for CI / automation)

And apm deps clean --help:

  -y, --yes  Skip confirmation prompt

• Suggested Fix: Add -y, --yes Skip the confirmation prompt (for CI / automation) to apm uninstall.

---

3. Inconsistent description wording between apm update and apm deps update

• Commands: apm update, apm deps update
• Problem: Both commands perform the same conceptual operation (refresh git refs and reinstall packages), but their one-line descriptions use different verbs and phrasing. apm update uses "Refresh", apm deps update uses "Update". Since apm deps update is deprecated in favor of apm update, clarifying the deprecation in the apm deps update one-liner would also help users understand the relationship.
• Evidence:

$ apm update --help
  Refresh APM dependencies to the latest matching refs

$ apm deps update --help
  Update APM dependencies to latest refs

• Suggested Fix: Update apm deps update's one-liner to something like "[Deprecated: use 'apm update'] Refresh APM dependencies to the latest matching refs", making the deprecation and canonical replacement explicit at the summary level.

---

Low Severity

4. Inconsistent trailing periods in top-level command descriptions

• Commands: pack, publish, self-update, targets, unpack
• Problem: Five top-level command descriptions in apm --help end with a trailing period; the remaining ~25 commands do not. This is a style inconsistency.
• Evidence (from apm --help, commands whose descriptions end with a period):

  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 (no trailing period -- representative):

  compile       Compile APM context into distributed AGENTS.md files
  config        Configure APM CLI
  deps          Manage APM package dependencies
  init          Initialize a new APM project
  mcp           Discover, inspect, and install MCP servers
  update        Refresh APM dependencies to the latest matching refs

• Suggested Fix: Remove trailing periods from pack, publish, self-update, targets, and unpack descriptions to match the majority convention.

---

5. apm compile --no-dedup / --no-force-instructions flag naming is a double-negative

• Command: apm compile
• Problem: The flag that enables inclusion of the instructions section in CLAUDE.md is named --no-dedup as its primary form. The action is positive ("Include the instructions section") but the primary flag name starts with --no-. The alias --force-instructions (mentioned only in the description text) is far more intuitive but is secondary. Users reading the help must mentally decode "no-dedup means include instructions" rather than immediately understanding the intent.
• Evidence:

$ apm compile --help
  --no-dedup / --no-force-instructions
                                  Include the instructions section in
                                  CLAUDE.md even when .claude/rules/ is
                                  already populated. Overrides the default
                                  deduplication that normally omits the
                                  section to avoid duplicate context in Claude
                                  Code. Affects the Claude target only. Alias:
                                  --force-instructions.

• Suggested Fix: Make --force-instructions the primary flag name (shown first in the option declaration) and keep --no-dedup as the backward-compatible alias. Update the help description to drop the "Alias:" note.

---

Clean Areas

The following commands and areas passed all checks:

• Error handling: All invalid-argument scenarios tested (apm install --nonexistent-flag, apm deps info with no arg, apm config set with no args) produced clean, actionable error messages with no tracebacks.
• -h / --help: Works on every command and subcommand inspected.
• apm init: Consistent flags; deprecation notices for --plugin and --marketplace are clear.
• apm install: Comprehensive option set, detailed descriptions, consistent with docs.
• apm update: Consistent with docs; has --yes, --dry-run, --verbose, -g.
• apm compile: Full option set, well-described (aside from finding apm install <my-apm-package-repo> #5 above).
• apm run: Clean, minimal, consistent with docs.
• apm deps list/tree/info/clean: Internally consistent within the subset; docs match CLI.
• apm mcp search/show/list: Consistent flags and descriptions; default limits match docs (search: 10, list: 20).
• apm config get/set/unset: Consistent with docs; docs accurately describe the absence of a list subcommand.
• apm runtime setup/list/status/remove: All subcommands exist as documented; apm runtime remove correctly exposes -y, --yes.
• Documentation cross-reference: All commands listed in docs/src/content/docs/reference/cli/ exist in the actual CLI. No phantom commands or missing pages detected.

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 · sonnet46 3.4M · ◷

• expires on Jun 13, 2026, 2:38 PM UTC