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

[github-actions]

CLI Consistency Report

Date: 2026-04-06
APM Version: 0.8.10 (44eebf1)
Commands Inspected: 38 (top-level + all subcommands)

Summary

Severity	Count
High	2
Medium	2
Low	3

---

High Severity

apm compile --target doc missing copilot and cursor targets

• Command: apm compile --help
• Problem: The CLI reference doc lists only [vscode|agents|claude|codex|opencode|all] as valid --target values, completely omitting copilot (the canonical current target) and cursor. This means users consulting the docs cannot discover the primary target value.
• Evidence:
  • CLI actual output: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  • docs/src/content/docs/reference/cli-commands.md line ~1092: -t, --target [vscode|agents|claude|codex|opencode|all]
• Suggested Fix: Update the apm compile --target option in the CLI reference to [copilot|claude|cursor|opencode|codex|vscode|agents|all] to match the actual CLI output.

apm compile --target doc incorrect alias description

• Command: apm compile --help
• Problem: The docs say "agents is an alias for vscode", but the actual CLI states 'vscode' and 'agents' are deprecated aliases for 'copilot'. This is factually wrong — both are deprecated aliases for copilot, not the other way around.
• Evidence:
  • CLI actual output: Target platform: copilot (AGENTS.md), claude (CLAUDE.md), cursor, opencode, or all. 'vscode' and 'agents' are deprecated aliases for 'copilot'.
  • docs/src/content/docs/reference/cli-commands.md line ~1092: `agents` is an alias for `vscode`. Auto-detects if not specified.
• Suggested Fix: Update the alias description to: `vscode` and `agents` are deprecated aliases for `copilot`.

---

Medium Severity

apm install --target doc missing deprecated alias values and short flag

• Command: apm install --help
• Problem: The CLI reference doc for apm install --target omits the vscode and agents deprecated values that still appear in the CLI, and omits the -t short flag.
• Evidence:
  • CLI actual output: -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  • docs/src/content/docs/reference/cli-commands.md line ~90: --target [copilot|claude|cursor|codex|opencode|all]
• Suggested Fix: Update the install --target documentation to include -t short flag and add vscode and agents as deprecated values with a note: `-t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]` — `vscode` and `agents` are deprecated aliases for `copilot`.

apm install --verbose flag documented without short -v form

• Command: apm install --help
• Problem: The CLI reference doc for apm install shows --verbose without the -v short form, but the actual CLI exposes both. This is inconsistent with every other command in the reference that documents it as -v, --verbose.
• Evidence:
  • CLI actual output: -v, --verbose Show detailed installation information
  • docs/src/content/docs/reference/cli-commands.md line ~95: --verbose - Show individual file paths and full error details in the diagnostic summary
• Suggested Fix: Update to -v, --verbose to match the actual CLI and the pattern used throughout the rest of the reference doc.

---

Low Severity

apm run labeled "(Experimental)" in docs but not in CLI help

• Command: apm run --help
• Problem: The CLI reference doc title reads apm run (Experimental) - Execute prompts, but the CLI help text shows only Run a script with parameters with no experimental label. Either the label should be added to the CLI help text or removed from the doc.
• Evidence:
  • CLI actual output: Run a script with parameters
  • docs/src/content/docs/reference/cli-commands.md line ~1001: ### \apm run` (Experimental) - Execute prompts`
• Suggested Fix: Add (Experimental) to the apm run help string in src/apm_cli/cli.py, or remove the label from the documentation.

apm runtime labeled "(Experimental)" in docs but not in CLI help

• Command: apm runtime --help
• Problem: The CLI reference doc marks the entire Runtime Management section as "(Experimental)" but the CLI help shows only Manage AI runtimes.
• Evidence:
  • CLI actual output: Manage AI runtimes
  • docs/src/content/docs/reference/cli-commands.md lines ~1328-1330: ## Runtime Management (Experimental) and ### \apm runtime` (Experimental) - Manage AI runtimes`
• Suggested Fix: Align the CLI help text with the docs by appending (Experimental) to the apm runtime command description, or remove the label from the docs if the feature is now stable.

apm deps update flag ordering inconsistency in docs

• Command: apm deps update --help
• Problem: The CLI reference doc lists the verbose flag as --verbose, -v (long form first), while the rest of the reference and the actual CLI output consistently use -v, --verbose (short form first).
• Evidence:
  • CLI actual output: -v, --verbose Show detailed update information
  • docs/src/content/docs/reference/cli-commands.md line ~754: --verbose, -v - Show detailed update information
• Suggested Fix: Change to -v, --verbose for consistency with the rest of the reference document.

---

Clean Areas

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

• apm init — options, flags, and doc description all match
• apm uninstall — flags documented correctly including -v, --verbose short form
• apm update — minimal flags, all match
• apm deps list, apm deps tree, apm deps info, apm deps clean — all correct
• apm mcp list, apm mcp search, apm mcp show — all match (including --limit default: 20)
• apm config get, apm config set — correct
• apm runtime setup, apm runtime list, apm runtime remove, apm runtime status — all match
• apm audit — extensive options all documented accurately
• apm marketplace (all subcommands) — all correct
• apm pack, apm unpack — all match
• apm prune, apm search, apm list, apm preview — all match
• Error handling — apm install --nonexistent-flag, apm deps info (no arg), apm config set (no args) all produce clean error messages with usage hints, no stack traces
• Exit codes — consistent and sensible across tested commands

Generated by CLI Consistency Checker · ◷

• expires on Apr 8, 2026, 1:36 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-04-08T13:36:18.553Z.

Closed by Workflow