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

[github-actions]

CLI Consistency Report

Date: 2026-04-07
APM Version: 0.8.11 (81082e2)
Commands Inspected: 39 (all top-level commands + every subcommand via --help)

Summary

Severity	Count
High	2
Medium	4
Low	2

---

High Severity

Box-drawing characters in CLI output strings

• Command: apm install (and any command that triggers collision/security errors)
• Problem: Three output strings in src/apm_cli/commands/install.py use box-drawing characters └─ (U+2514 U+2500), which fall outside printable ASCII (U+0020–U+007E). These will raise a UnicodeEncodeError: 'charmap' codec can't encode character on Windows cp1252 terminals, which is precisely the failure mode the project's ASCII encoding rule was written to prevent.
• Evidence:

  # src/apm_cli/commands/install.py:944-945
  logger.progress(f"  └─ Inspect source: {install_path}")
  logger.progress("  └─ Use --force to deploy anyway")
  
  # src/apm_cli/commands/install.py:1289
  _rich_error(f"  └─ {fail_msg}")
  

• Suggested Fix: Replace └─ with an ASCII equivalent. Per the project's STATUS_SYMBOLS convention, use [>] or indent with > for continuation lines:

  logger.progress(f"  [>] Inspect source: {install_path}")
  logger.progress("  [>] Use --force to deploy anyway")
  _rich_error(f"  [>] {fail_msg}")
  ```

---

Em dashes in CLI output strings

• Command: apm install, apm pack, apm audit (and related)
• Problem: Multiple user-facing output strings in Python source files use the em dash character — (U+2014), which is outside printable ASCII and will fail on Windows cp1252 terminals.
• Evidence:

  # src/apm_cli/integration/base_integrator.py:97
  f"Skipping {rel_path} — local file exists (not managed by APM). "
  
  # src/apm_cli/bundle/packer.py:92
  f"Cannot pack — apm.yml contains local path dependency: "
  
  # src/apm_cli/bundle/packer.py:193
  f"— run 'apm audit' to inspect before publishing"
  
  # src/apm_cli/bundle/plugin_exporter.py:445
  f"Cannot pack — apm.yml contains local path dependency: "
  
  # src/apm_cli/bundle/plugin_exporter.py:566
  f"source files — run 'apm audit' to inspect before publishing"
  
  # src/apm_cli/bundle/plugin_exporter.py:653
  f"{output_rel} — collision between '{existing_owner}' and "
  
  # src/apm_cli/security/gate.py:149
  f"{verdict.critical_count} critical finding(s) — "
  
  # src/apm_cli/security/gate.py:157
  "Blocked — critical hidden characters in source. "
  
  # src/apm_cli/security/gate.py:172, 182
  f"{verdict.warning_count} warning(s) — "
  

• Suggested Fix: Replace every — in user-visible string literals with - (space-hyphen-space):

  f"Skipping {rel_path} - local file exists (not managed by APM). "
  f"Cannot pack - apm.yml contains local path dependency: "
  f"{verdict.critical_count} critical finding(s) - "
  # etc.
  ```

---

Medium Severity

apm install --target docs missing deprecated aliases

• Command: apm install
• Problem: The CLI reference docs list the --target enum as [copilot|claude|cursor|codex|opencode|all] but the actual CLI accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all]. The deprecated aliases vscode and agents are present in the CLI but absent from the docs.
• Evidence:
  • Docs (docs/src/content/docs/reference/cli-commands.md:90):

    --target [copilot|claude|cursor|codex|opencode|all]
    

  • CLI (apm install --help):

    -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
    

• Suggested Fix: Update the docs to include vscode and agents in the enum list, noting they are deprecated aliases for copilot:

  --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  

  Add a note: `vscode` and `agents` are deprecated aliases for `copilot`.

---

apm compile --target docs missing copilot and cursor

• Command: apm compile
• Problem: The docs list --target as [vscode|agents|claude|codex|opencode|all], but the actual CLI accepts [copilot|claude|cursor|opencode|codex|vscode|agents|all]. Crucially, copilot (the new canonical target) and cursor are completely absent from the documented enum.
• Evidence:
  • Docs (docs/src/content/docs/reference/cli-commands.md:1092):

    -t, --target [vscode|agents|claude|codex|opencode|all]
    

  • CLI (apm compile --help):

    -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
                  Target platform: copilot (AGENTS.md), claude (CLAUDE.md),
                  cursor, opencode, or all.
                  'vscode' and 'agents' are deprecated aliases for 'copilot'.
    

• Suggested Fix: Update docs to reflect the full enum and deprecation notice:

  -t, --target [copilot|claude|cursor|opencode|codex|vscode|agents|all]
  

  Also update the auto-detection table (lines 1108-1113) and target format table (lines 1125-1131) to use copilot as the primary target name (replacing vscode), and add a row for cursor. Add a deprecation note for vscode and agents.

---

Deprecated compile target aliases still primary in docs auto-detection table

• Command: apm compile
• Problem: The compile auto-detection table and examples in the docs still use vscode as the canonical target name, but the CLI has demoted vscode to a deprecated alias. The docs do not mention that vscode is deprecated or that copilot is the new canonical name.
• Evidence:
  • CLI (apm compile --help): 'vscode' and 'agents' are deprecated aliases for 'copilot'. Auto-detects if not specified.
  • Docs (docs/src/content/docs/reference/cli-commands.md:1110):

    | .github/ exists only | vscode | AGENTS.md + .github/ |
    

  • Docs examples (line 1157): apm compile --target vscode # AGENTS.md + .github/ only
• Suggested Fix: Update the auto-detection table and examples to use copilot as the primary target. Add a deprecation callout:

  > **Note**: `--target vscode` and `--target agents` are deprecated aliases for `--target copilot`. They continue to work but will be removed in a future release.
  

---

apm install --verbose missing -v short form in docs

• Command: apm install
• Problem: The CLI reference docs list the verbose flag as --verbose without the -v short form, but the CLI implements both -v and --verbose.
• Evidence:
  • Docs (docs/src/content/docs/reference/cli-commands.md:95):

    --verbose - Show individual file paths and full error details...
    ```
    

  • CLI (apm install --help):

    -v, --verbose   Show detailed installation information
    

• Suggested Fix: Update the docs to include the short form: -v, --verbose

---

Low Severity

apm runtime remove missing -y short form for --yes

• Command: apm runtime remove
• Problem: apm runtime remove uses --yes without a -y short form. Every other confirmation-skip flag in the CLI uses -y, --yes. This is a minor inconsistency that makes the flag pattern harder to remember.
• Evidence:
  • apm deps clean --help: -y, --yes Skip confirmation prompt
  • apm marketplace remove --help: -y, --yes Skip confirmation
  • apm runtime remove --help: --yes Confirm the action without prompting (no -y)
• Suggested Fix: Add -y as a short alias for --yes in apm runtime remove, consistent with the rest of the CLI.

---

apm deps update docs show --verbose, -v (reversed notation)

• Command: apm deps update
• Problem: The docs list the verbose flag as --verbose, -v (long form first), but the CLI and every other command in the docs use the Click convention of short form first: -v, --verbose.
• Evidence:
  • Docs (docs/src/content/docs/reference/cli-commands.md:754):

    --verbose, -v - Show detailed update information
    

  • All other commands in docs and CLI: -v, --verbose
• Suggested Fix: Swap to -v, --verbose for consistency.

---

Clean Areas

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

• apm init: Help text clear, flags consistent, no issues.
• apm uninstall: Help text clear, --dry-run, -v, -g all consistent.
• apm update: Simple and correct.
• apm run: Consistent with apm preview.
• apm preview: Mirrors apm run interface exactly.
• apm list: Minimal, correct.
• apm deps list / deps tree / deps info / deps clean: All consistent.
• apm mcp list / mcp search / mcp show: All consistent with documented behavior.
• apm config get / config set: Correct and consistent.
• apm marketplace add/browse/list/remove/update: All consistent; -y, --yes pattern correct.
• apm runtime setup / runtime list / runtime status: Correct.
• apm pack / unpack / prune / audit / search: All consistent.
• Error handling: All commands tested produce sensible error messages (not stack traces) for missing/invalid arguments.
• apm mcp install / apm config list: These subcommands do not exist in the CLI — this is correct and expected. The task spec listed them to verify the CLI handles missing commands gracefully (it does: Error: No such command 'install').

Generated by CLI Consistency Checker · ◷

• expires on Apr 9, 2026, 1:41 PM UTC

[github-actions]

This issue was automatically closed because it expired on 2026-04-09T13:41:17.532Z.

Closed by Workflow