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

[github-actions]

CLI Consistency Report

Date: 2026-06-26
APM Version: 0.22.0 (f8c4244)
Commands Inspected: 27

Summary

Severity	Count
High	1
Medium	4
Low	1

---

High Severity

apm deps update missing deprecation notice in CLI help

• Command: apm deps update --help
• Problem: The CLI help text shows no deprecation notice. The docs (docs/src/content/docs/reference/cli/deps.md) explicitly warn that apm deps update is deprecated in favor of apm update, and the internal guide (packages/apm-guide/.apm/skills/apm-usage/commands.md) also marks it as "Deprecated -- use apm update instead". Users who discover the command through apm deps --help have no in-CLI signal to switch to apm update.
• Evidence:
  • CLI output: Usage: apm deps update [OPTIONS] [PACKAGES]... / Update APM dependencies to latest refs -- no deprecation mention
  • Docs: :::caution[Deprecated] \apm deps update` is deprecated in favor of `apm update`, which is now a strict superset...`
  • Compare: apm install --update DOES inline its deprecation: (deprecated: prefer 'apm update' for an interactive plan, or 'apm update --yes' for CI)
• Suggested Fix: Add a deprecation notice to the apm deps update description string, matching the pattern used by apm install --update. For example: change the command description to "Update APM dependencies to latest refs (deprecated: use 'apm update' instead, which is a strict superset)".

---

Medium Severity

apm install --runtime does not disclose it is a legacy alias

• Command: apm install --runtime
• Problem: The --runtime flag in CLI help describes itself as "Target specific runtime only (...)" with no indication that it is a deprecated legacy alias for --target. The install documentation explicitly calls it a "Legacy alias for --target (single value only). Still accepted; prefer --target." Users reading only CLI help are not guided toward --target.
• Evidence:
  • CLI output: --runtime TEXT Target specific runtime only (copilot, claude, codex, cursor, gemini, antigravity, intellij, kiro, opencode, vscode, windsurf)
  • Docs (docs/src/content/docs/reference/cli/install.md): | \--runtime VALUE` | unset | Legacy alias for `--target` (single value only). Still accepted; prefer `--target`. |`
• Suggested Fix: Update the --runtime help string to: "(Legacy alias for --target, single value only; prefer --target) Target specific runtime ...".

---

apm install --runtime lists vscode but --target does not

• Command: apm install --runtime vs apm install --target
• Problem: The --runtime flag lists vscode as a valid value (copilot, claude, codex, cursor, gemini, antigravity, intellij, kiro, opencode, vscode, windsurf) but the --target flag does NOT list vscode in its values. If vscode is a supported target, it should appear in --target; if it is not, it should be removed from --runtime.
• Evidence:
  • --runtime valid values from CLI help: copilot, claude, codex, cursor, gemini, antigravity, intellij, kiro, opencode, vscode, windsurf
  • --target valid values from CLI help: copilot, claude, cursor, opencode, codex, gemini, antigravity, windsurf, kiro, agent-skills, all
  • vscode appears in --runtime but not in --target
• Suggested Fix: Audit whether vscode is a functional target. If yes, add it to the --target enumerated values. If no, remove it from the --runtime help text.

---

apm compile --no-dedup / --no-force-instructions confusing flag naming

• Command: apm compile --help
• Problem: Both flag names in the pair start with --no- but the action described is a positive one ("Include the instructions section"). The actual usable alias (--force-instructions) is only mentioned in the description prose, not in the usage line. This creates a confusing double-negative (--no-force-instructions means "do NOT force-include", i.e. the default state).
• Evidence:
  • CLI output: --no-dedup / --no-force-instructions Include the instructions section in CLAUDE.md even when .claude/rules/ is already populated... Alias: --force-instructions.
  • The guide (packages/apm-guide/.apm/skills/apm-usage/commands.md) correctly lists it as --no-dedup / --force-instructions (positive alias shown)
  • Running apm compile --force-instructions works, but this alias is hidden in the options table
• Suggested Fix: Change the Click boolean flag definition to surface --force-instructions as the primary positive name and --no-force-instructions (or --no-dedup) as the disable form. The usage line should show --force-instructions / --no-force-instructions with --no-dedup listed as an alias in the description.

---

apm mcp install uses non-standard options presentation

• Command: apm mcp install --help
• Problem: The apm mcp install help shows only --help as an explicit option, then lists common forwarded options as freeform text after the options block. Users must separately consult apm install --help to discover flags like --transport, --url, --env, --dry-run, etc. The options are not machine-parseable and break the standard Click help contract.
• Evidence:

  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: Either declare the forwarded flags as explicit Click options on apm mcp install (matching their definitions in apm install), or at minimum move the prose list outside the Options: section using a Click epilog so help text renders cleanly. The current layout embeds unstructured text inside the options block.

---

Low Severity

apm deps info help does not mention it is an alias for apm view

• Command: apm deps info --help
• Problem: The help text says only "Show detailed package information" with no indication that it is equivalent to apm view PACKAGE for installed packages. The documentation (docs/src/content/docs/reference/cli/deps.md) says "Equivalent to apm view PACKAGE for installed packages; prefer apm view in new scripts." Users are not guided toward the canonical apm view command.
• Evidence:
  • CLI output: Usage: apm deps info [OPTIONS] PACKAGE / Show detailed package information
  • Docs: "Show detailed information about one installed package: manifest metadata, primitive inventory, and source. Equivalent to `apm view PACKAGE` for installed packages; prefer `apm view` in new scripts."
• Suggested Fix: Update the apm deps info description to: "Show detailed package information (alias for 'apm view PACKAGE' for installed packages; prefer 'apm view' in new scripts)".

---

Clean Areas

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

• apm --help: Top-level help, version flag, and common workflows section are accurate and complete.
• apm init --help: All flags documented; deprecated flags (--plugin, --marketplace) correctly note alternatives inline.
• apm install --help: Comprehensive flag documentation; inline deprecation notice on --update is correct. --frozen, --dry-run, and --force semantics are accurately described.
• apm uninstall --help: Consistent with documentation; --dry-run, -v, -g flags all present.
• apm update --help: Complete; -y, --dry-run, --verbose, --parallel-downloads all accurately described.
• apm compile --help (aside from --no-dedup naming): All other flags accurate.
• apm run --help: Correct; --param / -p and --verbose present.
• apm deps list/tree/clean/why --help: Flags consistent with documentation.
• apm mcp list/search/show --help: Default values consistent with docs (list default 20, search default 10).
• apm config / get / set / unset: Behavior matches documentation; apm config with no subcommand correctly prints a merged table.
• apm runtime setup/list/status/remove --help: All subcommands present and consistent with documentation.
• Error handling: All tested invalid-argument and missing-argument cases produce clean Error: messages, not stack traces. (apm install --nonexistent-flag, apm deps info (no arg), apm config set (no args), apm mcp search (no query).)
• apm unpack --help: Deprecation notice present and correctly points to apm install.

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 · 161.3 AIC · ⌖ 7.69 AIC · ⊞ 6.6K · ◷

• expires on Jun 28, 2026, 1:55 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-06-28T13:55:36.104Z.

Closed by Workflow