[cli-consistency] CLI Consistency Report — 2026-03-18

[github-actions]

CLI Consistency Report

Date: 2026-03-18
APM Version: 0.8.1 (d09b377)
Commands Inspected: 30 (12 core, 6 deps, 4 mcp, 3 config, 5 runtime)

Summary

Severity	Count
High	2
Medium	3
Low	1

---

High Severity

README incorrectly claims apm compile generates .cursor/rules/

• Command: apm compile
• Problem: README states apm compile produces .cursor/rules/ (Cursor), but apm compile has no Cursor output at all. Cursor rule generation is performed by apm install (via CursorClientAdapter), not compile. The compile command only supports vscode|agents|claude|opencode|all targets — there is no cursor target.
• Evidence:
  • README.md line 43: apm compile produces AGENTS.md (GitHub Copilot, OpenCode), CLAUDE.md (Claude Code), and .cursor/rules/ (Cursor)
  • apm compile --help output: -t, --target [vscode|agents|claude|opencode|all] — no cursor option
  • src/apm_cli/compilation/ directory: zero references to cursor, .mdc, or cursor/rules
• Suggested Fix: Update README.md line 43 to accurately describe what apm compile produces. Remove the .cursor/rules/ claim. For example:

  apm compile produces AGENTS.md (GitHub Copilot, OpenCode), CLAUDE.md (Claude Code) — Cursor rules are deployed by apm install.

---

apm compile --target option docs missing opencode target

• Command: apm compile
• Problem: The CLI reference docs list [vscode|agents|claude|all] as the valid --target values for apm compile, but the actual CLI also accepts opencode. Users trying to compile for an OpenCode project explicitly cannot find this option in the docs.
• Evidence:
  • docs/src/content/docs/reference/cli-commands.md line 857:
    -t, --target [vscode|agents|claude|all] — missing opencode
  • apm compile --help actual output:
    -t, --target [vscode|agents|claude|opencode|all] — opencode is supported
• Suggested Fix: Update line 857 of cli-commands.md to:
  -t, --target [vscode|agents|claude|opencode|all] — Target platform: vscode/agents (AGENTS.md), claude (CLAUDE.md), opencode (AGENTS.md), or all. Auto-detects if not specified.

---

Medium Severity

apm compile Target Formats table missing opencode and agents rows

• Command: apm compile
• Problem: The "Target Formats (explicit)" table in the docs only shows vscode, claude, and all. It is missing opencode (which generates AGENTS.md for OpenCode projects) and agents (an alias for vscode). The table also does not mention Cursor integration output at all — since cursor is handled by install, a brief note would prevent user confusion.
• Evidence:
  • cli-commands.md lines 889–893 table:

    | vscode | AGENTS.md, .github/prompts/, .github/agents/, .github/skills/ | GitHub Copilot, Cursor, Codex, Gemini |
    | claude | CLAUDE.md, .claude/commands/, SKILL.md                        | Claude Code, Claude Desktop           |
    | all    | All of the above                                              | Universal compatibility               |
    ```
    

  • CLI supports 5 targets: vscode, agents, claude, opencode, all
  • src/apm_cli/core/target_detection.py:143: opencode target generates AGENTS.md
• Suggested Fix: Add rows for opencode and agents to the table:

  | agents   | (alias for vscode) Same as vscode                           | Alternative alias for vscode          |
  | opencode | AGENTS.md, .opencode/agents/, .opencode/commands/           | OpenCode                              |
  

---

apm compile Target Auto-Detection table missing .opencode/ case

• Command: apm compile
• Problem: The "Target Auto-Detection" table shows only three detection cases (.github/, .claude/, both/neither), but the actual detection logic also handles the case where only .opencode/ exists, returning opencode as the detected target.
• Evidence:
  • cli-commands.md lines 873–878 (no .opencode/ row shown):

    | .github/ exists only      | vscode  | AGENTS.md + .github/ |
    | .claude/ exists only      | claude  | CLAUDE.md + .claude/ |
    | Both folders exist        | all     | All outputs          |
    | Neither folder exists     | minimal | AGENTS.md only       |
    

  • src/apm_cli/core/target_detection.py lines 73, 88–89:

    opencode_exists = (project_root / ".opencode").is_dir()
    ...
    elif opencode_exists:
        return "opencode", "detected .opencode/ folder"

• Suggested Fix: Add the missing row to the table:
  | .opencode/ exists only | opencode | AGENTS.md (opencode integration) |

---

apm install --verbose help text too vague

• Command: apm install
• Problem: The --verbose flag help text in the CLI is unhelpfully brief compared to what it actually does.
• Evidence:
  • apm install --help output: --verbose Show detailed installation information
  • cli-commands.md line 88 (more accurate): --verbose - Show individual file paths and full error details in the diagnostic summary
• Suggested Fix: Update the --verbose help text in src/apm_cli/commands/install.py to match the documentation: "Show individual file paths and full error details in the diagnostic summary"

---

Low Severity

apm compile --target option description: "agent format" vs "platform"

• Command: apm compile
• Problem: The docs describe --target as "Target agent format" while the CLI says "Target platform". Minor but inconsistent terminology.
• Evidence:
  • Docs line 857: Target agent format. 'agents' is an alias for 'vscode'.
  • CLI: Target platform: vscode/agents (AGENTS.md), claude (CLAUDE.md), opencode (AGENTS.md), or all.
• Suggested Fix: Align docs to say "Target platform" to match the CLI.

---

Clean Areas

The following commands passed all checks with no issues found:

• apm init — options documented correctly, behavior consistent
• apm uninstall — correct, dry-run documented
• apm update — correct, --check documented
• apm run / apm preview — consistent -p/--param flag, correct
• apm list — minimal, correct
• apm pack — target options (copilot|vscode|claude|cursor|opencode|all) match docs exactly
• apm unpack — all flags match docs
• apm prune — correct
• apm audit — all flags (--file, --strip, -v, --dry-run, -f, -o) match docs
• apm deps list/tree/info/clean/update — all documented and working correctly
• apm mcp list/search/show — options match docs (no install subcommand exists or is documented)
• apm config get/set — correct (no list subcommand exists or is documented; apm config without args correctly shows current config as documented)
• apm runtime setup/list/remove/status — all documented and consistent
• Error handling: Invalid flags, missing required args — all produce clean Click error messages with usage hints, no stack traces

Generated by CLI Consistency Checker · ◷

• expires on Mar 20, 2026, 2:34 PM UTC