[cli-consistency] CLI Consistency Report — 2026-04-23

[github-actions]

CLI Consistency Report

Date: 2026-04-23
APM Version: 0.9.2 (aa26b31)
Commands Inspected: 38 (including all subcommands for deps, mcp, config, runtime, marketplace, policy)

Summary

Severity	Count
High	0
Medium	6
Low	3

---

Medium Severity

M1: apm mcp install --help is missing its positional argument and all flags

• Command: apm mcp install --help
• Problem: The usage line says apm mcp install [OPTIONS] — no positional NAME argument is shown, and no flags (e.g. --transport, --url, --env) appear in the Options section, even though the embedded examples use them. A user reading only --help would not know the command requires a name or accepts any of the install flags.
• Evidence:

  Usage: apm mcp install [OPTIONS]
  
    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.
  ```
  The examples show a required positional argument (`fetch`, `api`) and options (`--transport`, `--url`) that are never documented in the help output.
  

• Suggested Fix: Update the usage to apm mcp install NAME [OPTIONS] [-- COMMAND ARGS...] and forward/display the relevant flags (--transport, --url, --env, --header, --mcp-version, --registry) so the alias is genuinely self-documenting, or at minimum add a note like Run 'apm install --help' for available options.

---

M2: apm init — --verbose / -v flag undocumented in CLI reference

• Command: apm init --help
• Problem: The CLI exposes a -v, --verbose flag on apm init, but docs/src/content/docs/reference/cli-commands.md does not list it in the Options section for apm init.
• Evidence (CLI):

  Options:
    -y, --yes      Skip interactive prompts and use auto-detected defaults
    --plugin       Initialize as plugin author (creates plugin.json + apm.yml)
    -v, --verbose  Show detailed output
    --help         Show this message and exit.
  

  Docs only list -y, --yes and --plugin. No mention of -v, --verbose.
• Suggested Fix: Add - \-v, --verbose` - Show detailed outputto theapm initOptions section incli-commands.md`.

---

M3: apm pack — --verbose / -v flag undocumented in CLI reference

• Command: apm pack --help
• Problem: The CLI exposes -v, --verbose on apm pack, but the Options section in cli-commands.md omits it.
• Evidence (CLI):

  Options:
    --format [apm|plugin]  Bundle format.
    -t, --target TARGET    ...
    --archive              Produce a .tar.gz archive.
    -o, --output PATH      Output directory (default: ./build).
    --dry-run              Show what would be packed without writing.
    --force                On collision, last writer wins.
    -v, --verbose          Show detailed packing information
    --help                 Show this message and exit.
  

  Docs list 6 options but omit -v, --verbose.
• Suggested Fix: Add - \-v, --verbose` - Show detailed packing informationto theapm packOptions section incli-commands.md`.

---

M4: apm mcp list — --verbose / -v flag undocumented in CLI reference

• Command: apm mcp list --help
• Problem: The CLI exposes -v, --verbose on apm mcp list, but cli-commands.md only lists --limit.
• Evidence (CLI):

  Options:
    --limit INTEGER  Number of results to show  [default: 20]
    -v, --verbose    Show detailed output
    --help           Show this message and exit.
  

  Docs list only --limit INTEGER - Number of results to show (default: 20).
• Suggested Fix: Add - \-v, --verbose` - Show detailed outputto theapm mcp listOptions section incli-commands.md`.

---

M5: apm deps tree — -g, --global flag undocumented in CLI reference

• Command: apm deps tree --help
• Problem: The CLI exposes a -g, --global flag on apm deps tree to show the user-scope dependency tree, but the docs make no mention of this option.
• Evidence (CLI):

  Usage: apm deps tree [OPTIONS]
  
    Show dependency tree structure
  
  Options:
    -g, --global  Show user-scope dependency tree (~/.apm/)
    --help        Show this message and exit.
  

  Docs show only a bare apm deps tree with no options listed.
• Suggested Fix: Add an Options section under apm deps tree in cli-commands.md:

  **Options:**
  - `-g, --global` - Show user-scope dependency tree (`~/.apm/`)
  

---

M6: apm compile — copilot used in example but not in documented valid target values

• Command: apm compile --target / -t
• Problem: The cli-commands.md docs enumerate the valid --target values as [vscode|agents|claude|codex|opencode|all] — copilot is not listed. Yet two lines later, an example uses apm compile -t claude,copilot. This internal contradiction will confuse users.
• Evidence (docs cli-commands.md, lines ~1350 and ~1427):

  -t, --target [vscode|agents|claude|codex|opencode|all] - Target agent format.
  

  # Multiple targets (comma-separated)
  apm compile -t claude,copilot  # Both CLAUDE.md and AGENTS.md
  ```
  `copilot` appears in the example but is absent from the documented valid values.

• Suggested Fix: Either add copilot to the enumerated list (if it is a supported alias for vscode) or change the example to use vscode instead of copilot. Whichever is accurate should be applied consistently in both the list and the example.

---

Low Severity

L1: apm outdated --help one-liner ends with a trailing period

• Command: apm outdated --help
• Problem: The top-level apm --help and all other commands use descriptions without a trailing period. apm outdated is the only command whose brief description ends with a period: "Show outdated locked dependencies.".
• Evidence:

  Usage: apm outdated [OPTIONS]
  
    Show outdated locked dependencies.
  

  All other commands (e.g. Show dependency tree structure, Remove all APM dependencies, List installed APM dependencies) have no trailing period.
• Suggested Fix: Remove the trailing period from the apm outdated help string: "Show outdated locked dependencies".

---

L2: apm prune --help missing -v, --verbose flag

• Command: apm prune --help
• Problem: apm prune does not expose a -v, --verbose flag, unlike every semantically similar destructive/cleanup command (apm uninstall, apm deps clean, apm deps update). This is a minor UX inconsistency.
• Evidence:

  Usage: apm prune [OPTIONS]
  
    Remove APM packages not listed in apm.yml
  
  Options:
    --dry-run  Show what would be removed without removing
    --help     Show this message and exit.
  

  Compare with apm uninstall --help which has -v, --verbose Show detailed removal information.
• Suggested Fix: Add -v, --verbose to apm prune for consistency with sibling commands.

---

L3: Docs version-update example uses warning emoji instead of ASCII bracket notation

• Location: docs/src/content/docs/reference/cli-commands.md (Update Checking section)
• Problem: The sample CLI output in the docs uses the warning emoji (⚠️) in violation of the project's cross-platform ASCII-only encoding rule. Per project convention, warnings should use [!].
• Evidence (docs):

  ⚠️  A new version of APM is available: 0.7.0 (current: 0.6.3)
  Run apm update to upgrade
  

• Suggested Fix: Replace the emoji with the ASCII bracket notation:

  [!] A new version of APM is available: 0.7.0 (current: 0.6.3)
      Run 'apm update' to upgrade.
  

  Also verify the actual runtime output of the update notification in source code uses [!] (STATUS_SYMBOLS["warning"]) and not the emoji.

---

Clean Areas

The following commands and areas passed all checks with no issues found:

• apm init, apm install, apm uninstall, apm update, apm run, apm preview, apm list, apm compile, apm audit: flags, argument names, and descriptions all consistent and functional.
• apm deps list, apm deps info, apm deps clean, apm deps update: consistent with docs.
• apm mcp search, apm mcp show: docs and CLI match.
• apm config get, apm config set: behave as documented; sensible error messages on missing arguments.
• apm marketplace add, apm marketplace browse, apm marketplace list, apm marketplace remove, apm marketplace update, apm marketplace validate: all subcommands exist and match docs.
• apm policy status: flags and behavior consistent with docs.
• apm runtime list, apm runtime remove, apm runtime setup, apm runtime status: all subcommands exist and match docs.
• apm pack, apm unpack, apm view, apm outdated, apm search, apm prune: no structural doc drift (minor style notes filed above).
• Error handling: apm install --nonexistent-flag, apm deps info (missing arg), apm config set (missing arg) all produce clean error messages with usage hints — no stack traces.
• Exit behavior: All tested invalid-input scenarios exit cleanly with code 2.

Generated by CLI Consistency Checker · ◷

• expires on Apr 25, 2026, 1:38 PM UTC

[danielmeppiel]

Triaged under the new portability/security/governance roadmap (see #116).

Triage decision

auto-handle: close -- this is an automated daily CLI consistency
report with no High-severity findings (6 Medium, 3 Low, all about
self-documenting --help output and missing flag entries in
cli-commands.md).

Auto-handled: superseded by current taxonomy refactor; daily report
will regenerate if drift persists. The Medium items (apm mcp install --help, missing -v, --verbose doc entries) should be re-filed as
focused type/docs + area/cli issues if they are not auto-resolved
by the next report cycle.

Proposed labels

type/automation
area/cli
status/blocked

Milestone

null

Suggested next action

Close. If a Medium item persists across two consecutive daily reports,
file it as a standalone type/docs + area/cli issue so it gets
proper triage and a docs-site fix lane.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The apm mcp install --help finding is a real DX gap (the alias
should be self-documenting), and the cli-commands.md drift items
are normal docs-sync hygiene -- both are better tracked as individual
issues than as a rolling report.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. Pure CLI ergonomics + docs drift.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is the app/github-actions automation bot.

APM CEO -- Triage Arbiter

Daily auto-reports are signal, not backlog. Close per the
auto-handle rubric; tomorrow's report will resurface anything still
broken.