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

[github-actions]

CLI Consistency Report

Date: 2026-03-17
APM Version: 0.8.0
Commands Inspected: 32 (30 successful, 2 non-existent subcommands tested)

Summary

Severity	Count
High	1
Medium	3
Low	2

---

High Severity

apm compile --target missing opencode in documentation

• Command: apm compile --help
• Problem: The CLI supports opencode as a valid --target value but it is completely absent from the CLI reference docs (docs/src/content/docs/reference/cli-commands.md).
• Evidence (CLI):

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

• Evidence (docs, line 857):

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

• Suggested Fix: Update the apm compile options section in docs/src/content/docs/reference/cli-commands.md line 857 to:

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

  Also add opencode to the examples section (lines 919–921).

---

Medium Severity

apm install --verbose help text is too terse

• Command: apm install --help
• Problem: The CLI help text says only Show detailed installation information, which doesn't explain what "detailed" means. The docs describe the actual behavior much more precisely.
• Evidence (CLI):

  --verbose    Show detailed installation information
  

• Evidence (docs, line 88):

  `--verbose` - Show individual file paths and full error details in the diagnostic summary
  

• Suggested Fix: Update src/apm_cli/commands/install.py line 303 help string to:

  help="Show individual file paths and full error details in the diagnostic summary"
  ```

apm pack --format missing default value in CLI help output

• Command: apm pack --help
• Problem: The --format option has a hardcoded default="apm" in source (src/apm_cli/commands/pack.py line 18) but lacks show_default=True, so the help text reads Bundle format. with no default shown. The docs correctly document (default: apm).
• Evidence (CLI):

  --format [apm|plugin]    Bundle format.
  

• Evidence (docs, line 410):

  `--format [apm|plugin]` - Bundle format (default: `apm`)
  

• Suggested Fix: Add show_default=True to the --format option in src/apm_cli/commands/pack.py:

  `@click`.option(
      "--format", "fmt",
      type=click.Choice(["apm", "plugin"]),
      default="apm",
      show_default=True,
      help="Bundle format.",
  )
  ```

apm audit --dry-run missing constraint in CLI help text

• Command: apm audit --help
• Problem: The --dry-run flag for apm audit requires --strip to be meaningful, but the CLI help text doesn't mention this constraint. The docs explicitly note it.
• Evidence (CLI):

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

• Evidence (docs, line 347):

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

• Suggested Fix: Update the --dry-run help string in the audit command to include the requires --strip note:

  help="Preview what --strip would remove without modifying files (requires --strip)"

---

Low Severity

apm compile examples in docs missing opencode target

• Command: apm compile
• Problem: The docs examples section for apm compile --target (lines 919–921) shows vscode, claude, and all but never shows opencode, even though it is a valid and supported target value.
• Evidence (docs, lines 919–921):

  apm compile --target vscode    # AGENTS.md + .github/ only
  apm compile --target claude    # CLAUDE.md + .claude/ only
  apm compile --target all       # All formats (default)

• Suggested Fix: Add an opencode example:

  apm compile --target opencode  # AGENTS.md + .opencode/ only
  ```
  

apm mcp list --limit shows no default; inconsistent with apm mcp search --limit

• Command: apm mcp list --help vs apm mcp search --help
• Problem: apm mcp search --limit shows [default: 10] in the help output, but apm mcp list --limit shows no default value, even though the docs document no default for mcp list either. This creates a confusing inconsistency: a user calling apm mcp list without --limit doesn't know how many results to expect.
• Evidence (CLI — mcp search):

  --limit INTEGER    Number of results to show  [default: 10]
  

• Evidence (CLI — mcp list):

  --limit INTEGER    Number of results to show
  

• Suggested Fix: If apm mcp list has a default limit, add show_default=True to the option. If it has no limit (returns all results), clarify with help="Max results to show (default: all)".

---

Clean Areas

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

• apm init — arguments, options, and help text all match docs
• apm install — all options present and documented (except --verbose verbosity above)
• apm uninstall — clean
• apm update — clean
• apm run — clean
• apm list — clean
• apm preview — clean
• apm pack — options and behavior match docs (except --format default display)
• apm unpack — clean
• apm prune — clean
• apm audit — clean (except --dry-run note)
• apm deps (all subcommands: list, tree, info, clean, update) — clean
• apm mcp (list, search, show) — clean
• apm config (default display, get, set) — clean
• apm runtime (setup, list, remove, status) — clean
• Error handling — all invalid inputs produce clean error messages (no stack traces)

Generated by CLI Consistency Checker · ◷

• expires on Mar 19, 2026, 1:39 PM UTC

[JiwaniZakir]

Investigating this now, should have a patch shortly.

[github-actions]

This issue was automatically closed because it expired on 2026-03-19T13:39:45.664Z.

Closed by Workflow