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

[github-actions]

CLI Consistency Report

Date: 2026-03-19
APM Version: 0.8.2 (64a70d4)
Commands Inspected: 31

Summary

Severity	Count
High	1
Medium	1
Low	1

---

High Severity

apm compile --target documentation missing opencode option

• Command: apm compile --target
• Problem: The CLI accepts opencode as a valid target but the reference documentation omits it. Users reading the docs have no way to know opencode is a supported compile target. The "Target Formats" table and all examples in the apm compile section also omit opencode, even though apm pack --target docs correctly include it.
• Evidence:
  • Actual CLI output (apm compile --help):

    -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.
    ```
    

  • Docs (docs/src/content/docs/reference/cli-commands.md, line 857):

    -t, --target [vscode|agents|claude|all]  - Target agent format. `agents` is an alias for `vscode`. Auto-detects if not specified.
    

  • The compile Target Formats table (line ~890) lists only vscode, claude, and all; opencode is absent. The examples at lines 919–921 likewise omit opencode.
• Suggested Fix: Update line 857 of cli-commands.md to [vscode|agents|claude|opencode|all]. Add opencode to the Target Formats table (output: AGENTS.md, .opencode/agents/, .opencode/commands/, .opencode/skills/; best for: OpenCode). Add an example: apm compile --target opencode # AGENTS.md + .opencode/ only.

---

Medium Severity

governance.md pre-commit hook example uses non-existent apm audit --drift flag

• Command: apm audit --drift
• Problem: The governance.md "Drift detection" section contains a working-looking .pre-commit-config.yaml code block with entry: apm audit --drift. This flag does not exist in the CLI. While the section has a :::note[Planned Feature]::: admonition, the code block is indistinguishable from working configuration, and users copying it will get an error.
• Evidence:
  • Running apm audit --drift returns:

    Error: No such option: --drift  Did you mean --dry-run?
    

  • docs/src/content/docs/enterprise/governance.md (lines ~210–222):

    # .pre-commit-config.yaml
    repos:
      - repo: local
        hooks:
          - id: apm-drift
            name: APM drift check
            entry: apm audit --drift
            language: system
            pass_filenames: false
    ```

  • The same file at line 213 also shows apm audit --drift --ci as a runnable command example.
• Suggested Fix: Wrap the pre-commit YAML code block and the apm audit --drift --ci example in a comment or replace them with a placeholder showing the intended syntax once the feature ships. Alternatively, add a visible # NOT YET AVAILABLE comment inside the code block.

---

Low Severity

apm audit --dry-run docs overstate a requirement not enforced by the CLI

• Command: apm audit --dry-run
• Problem: The CLI reference docs describe --dry-run as "Preview what --strip would remove without modifying files (requires --strip)". The CLI help text does not state this requirement, and the CLI does not enforce it — running apm audit --dry-run without --strip exits cleanly (with an informational message if no packages are found). The discrepancy creates confusion about when --dry-run is valid.
• Evidence:
  • CLI help (apm audit --help):

    --dry-run   Preview what --strip would remove without modifying files
    

  • Docs (cli-commands.md, ~line 348):

    --dry-run - Preview what --strip would remove without modifying files (requires --strip)
    

  • Running apm audit --dry-run alone exits with code 0 and prints No apm.lock.yaml found — nothing to scan.
• Suggested Fix: Either (a) remove "(requires --strip)" from the docs to match the CLI's actual permissive behavior, or (b) add a runtime guard in the CLI that exits with a usage error when --dry-run is supplied without --strip, and update the CLI help text accordingly.

---

Clean Areas

All of the following commands and areas passed all checks — help text is present, accurate, consistent with documentation, and error cases produce clean messages (no stack traces):

• apm --help, apm --version
• apm init, apm install, apm uninstall, apm update, apm run
• apm deps (and all subcommands: list, tree, info, clean, update)
• apm mcp (and subcommands: list, search, show)
• apm config (and subcommands: get, set; apm config with no args correctly shows current configuration)
• apm runtime (and subcommands: setup, list, remove, status)
• apm list, apm preview, apm pack, apm unpack, apm prune
• apm audit (flag set, exit codes, format options all accurate)
• apm compile (all flags documented except the opencode target omission noted above)
• Error handling: invalid flags and missing required arguments all produce clean Error: messages with usage hints — no stack traces observed
• apm audit --ci references in docs are consistently labelled as "planned" across all pages; no doc asserts it works today (except governance.md's code block noted above)

Generated by CLI Consistency Checker · ◷

• expires on Mar 21, 2026, 1:36 PM UTC