BranchPy CLI Reference (v1.1.1)

Authoritative reference for all BranchPy CLI commands, flags, and outputs. The CLI is the single source of truth; UI panels and automations wrap this contract.

Audience and stability

• For engineers, SRE/QA, and extension integrators.
• Namespaces: bpy.* is preferred; branchpy.* is legacy (removal no earlier than v0.7.1). Both shown where relevant.
• Exit codes and outputs follow Technical/errors/README.md. JSON/JSONL are stable; human text may change format but not substance.

Conventions and global behavior

• Global options (all commands unless noted): --help, --json, --format text|json|html, --project/-p <path>, --verbose, --quiet, --no-color, --config <file>.
• Data and logs: .branchpy/ under the project; user-level cache/logs at %LOCALAPPDATA%/BranchPy (Windows) or ~/.local/share/BranchPy (macOS/Linux).
• Event emission: BRANCHPY_EMIT_NOTIFY (JSON lines on stdout) and BRANCHPY_EMIT_EVENTS (stderr with BRANCHPY_EVENT:) follow Technical/telemetry/jsonl-events.md and Technical/events/catalog.md.
• Error taxonomy and exit codes: see Technical/errors/README.md. Common codes: 0 success, 1 issues found, 2 command/usage error, 3 configuration error, 4 environment error, 5 SDK error.
• Auth/licensing failures route to Technical/auth-licensing-sso/troubleshooting.md.
• Analysis outputs (CFG/SAE/PFI) are defined in Technical/analysis/ and referenced by analysis commands.

Table of contents

• Getting started / meta
• Project / SDK management
• Analysis and reporting
• Compare
• Doctor
• Image validation
• Media validation
• History / patches
• Logs / observability hooks
• Future / planned

Command index

• Getting started: help, version, update, guard
• Project / SDK: renpy (detect, list, add, remove, use, default, validate), config
• Analysis: analyze, tests (matrix), stats, report
• Compare: compare
• Doctor: doctor
• Image validation: image-validate
• Media: media
• History/patches: history (undo/redo/show/clear), patches, undo, redo
• Logs/observability: logs, JSONL emit toggles
• Planned: serve, cache

Getting started / meta

help

• Purpose: List available commands and show per-command usage.
• Syntax: bpy help [command]
• Core options: --json (machine-readable), --format text|json.
• Inputs/outputs: Reads command registry; outputs help text or JSON.
• Examples: bpy help, bpy help tests.
• Exit codes: 0 success; 2 if command not found.
• See also: Technical/errors/README.md.

version

• Purpose: Show BranchPy CLI version and build metadata.
• Syntax: bpy version
• Outputs: Human text; use --json for structured.
• Exit codes: 0 success.

update

• Purpose: Check for CLI updates and apply atomically.
• Syntax: bpy update
• Options: --preview (no apply), --json.
• Exit codes: 0 up-to-date/success; 1 update applied with warnings; 2 failure.

guard

• Purpose: Policy/quality gate before commits or deployments.
• Syntax: bpy guard [options]
• Behavior: Runs policy checks (same policy engine as policy run if configured) and exits non-zero on violation.
• Exit codes: 0 pass; 1 policy failures; 2 runtime error.
• See also: Technical/governance.

Project / SDK management

renpy (detect | list | add | remove | use | default | validate)

• Purpose: Manage Ren’Py SDK registry and project pins.
• Syntax: bpy renpy <subcommand> [options]
• Core options:
  • detect: --paths <p1,p2>, --json, --dry-run
  • list: --json, --validate, --compact, --show-paths
  • add: <name> <path>, --force, --validate, --set-default
  • remove: <name>, --force, --cleanup
  • use: <name>, --project <path>, --global
  • default: <name> | --clear
  • validate: [name], --json, --fix, --verbose
• Inputs: SDK paths and registry stored in .branchpy.toml and global config.
• Outputs: Human text or JSON; writes registry and project pins.
• Examples: bpy renpy detect, bpy renpy use sdk-8.1.3, bpy renpy list --validate.
• Exit codes: 0 success; 1 command failed (SDK invalid/missing); 2 invalid args/config.
• See also: Technical/analysis/cfg.md for matrix usage.

config

• Purpose: Manage project configuration (.branchpy.toml).
• Syntax: bpy config <init|show|get|set|unset|list> ...
• Core options: --project <path>, --json.
• Inputs: Config files (.branchpy.toml, user-level defaults).
• Outputs: Human text or JSON; writes config when setting values.
• Exit codes: 0 success; 3 configuration error (parse/permission); 2 usage error.
• See also: Technical/cli/configuration.md.

Analysis and reporting

analyze

• Purpose: Full project analysis (reachability, label integrity, semantics) using CFG/SAE engines.
• Syntax: bpy analyze -p <project> [--format text|json|html] [--save-report] [--matrix <sdks>] [--assets] [--out <dir>] [--emit-notify] [--json].
• Inputs: Ren’Py project files; optional assets when --assets.
• Outputs: Analysis report (text/JSON/HTML); optional saved report under .branchpy/analyze/ or user cache.
• Exit codes: 0 no blocking issues; 1 issues found; 2 analysis failed (syntax/file); 4 environment error.
• See also: Technical/analysis/README.md, Technical/analysis/troubleshooting.md.

tests

• Purpose: Core analyzer (missing jumps, orphan labels, unreachable code, variable checks) with optional matrix.
• Syntax: bpy tests [-p <project>] [--matrix <sdk list>] [--save-report] [--emit-notify] [--json] [--verbose].
• Inputs: Project scripts; optional SDK list.
• Outputs: Console summary; optional saved report .branchpy/reports/ and JSON.
• Exit codes: 0 clean; 1 issues found; 2 command/analysis failure.
• See also: Technical/analysis/pfi.md, compare.

stats

• Purpose: Variable and flag consistency (SAE-based).
• Syntax: bpy stats [-p <project>] [--format text|json|html] [--save] [--out <dir>].
• Outputs: Variable tables with file:line links; saved stats under .branchpy/stats/.
• Exit codes: 0 success; 1 issues; 2 command error.

report

• Purpose: Manage saved analysis reports.
• Syntax: bpy report <list|show|export|clean> [options]
• Core options: --format text|json|html, --last N, --before DATE, --after DATE, --out <path>.
• Outputs: Report listings and exports.
• Exit codes: 0 success; 2 usage error.

Compare

compare

• Purpose: Compare two analysis reports (labels, jumps, issues) for drift/regression.
• Syntax: bpy compare --old <source> --new <source> [--format text|json] [--changes-only] [--out <path>].
• Sources: last, last-N, timestamps, or file paths.
• Outputs: Human diff or JSON; can write to file with --out.
• Exit codes: 0 no differences; 1 differences found; 2 error.
• See also: Technical/analysis/README.md, Technical/cli/quick-reference.md.

Doctor

doctor

• Purpose: Environment and configuration diagnostics with Ren’Py SDK validation.
• Syntax: bpy doctor [--project <path>] [--verbose] [--json] [--emit-notify].
• Checks: Python env, BranchPy install, config, SDK registry, VS Code bridge, disk/paths.
• Outputs: Human or JSON diagnostics; emits JSONL when --emit-notify.
• Exit codes: 0 pass; 1 warnings/issues; 2 critical failure; 10 internal error.
• See also: Technical/telemetry/troubleshooting.md.

Image validation

image-validate

• Purpose: Scan all project images for quality and consistency issues � exact duplicates, resolution spread across a group, and mixed naming conventions (underscores vs hyphens).
• Syntax: branchpy --project <path> image-validate [options]
• Core options:
  • --project / -p <path> � project root (default: current directory)
  • --engine <name> � engine classifier: renpy (default), unity, godot, unreal, generic
  • --include-gui � include engine GUI assets (e.g. game/gui/) in output; excluded by default
  • --json � write ClustersPayloadV2 JSON to stdout; required for the VS Code Image Validation panel
  • --html � write a self-contained HTML report to .branchpy/reports/image-validation.html
  • --open � write the HTML report and open it immediately in the system browser (implies --html)
• Inputs: All image files (.png, .jpg, .jpeg, .webp) found under the project root; skips .git, node_modules, __pycache__, .venv, and similar noise folders.
• Outputs:
  • Human summary (default): group list with status icons and issue counts
  • JSON (with --json): ClustersPayloadV2 payload to stdout � consumed by the VS Code panel
  • HTML report (with --html or --open): .branchpy/reports/image-validation.html � dark-themed, self-contained, embeds full JSON payload
• Examples:

  # Human-readable summary
  branchpy --project /path/to/project image-validate
  
  # JSON for VS Code panel or scripting
  branchpy --project /path/to/project image-validate --json
  
  # Write standalone HTML report
  branchpy --project /path/to/project image-validate --html
  
  # Write HTML report and open in browser
  branchpy --project /path/to/project image-validate --open

• Exit codes: 0 success; 1 issues found; 2 error.
• See also: User Guide � Image Validation, Media validation.

Media validation

media

• Purpose: Media asset inspection (missing/unused/validate/optimize).
• Syntax: bpy media [--missing|--unused|--validate|--optimize] [--assets <path>] [--ext <list>] [--recursive] [--json].
• Outputs: Human or JSON listings; integrates with analysis when combined.
• Exit codes: 0 success; 1 issues found; 2 error.

History / patches

history (undo | redo | show | clear)

• Purpose: Manage reversible operations with audit trail.
• Syntax: bpy history <subcommand> [options]
  • undo: [STEPS], --json, --emit-notify
  • redo: [STEPS], --json, --emit-notify
  • show: --limit <N>, --json
  • clear: --force
• Outputs: Human or JSON; JSONL events when emit enabled.
• Exit codes: 0 success; 1 no operations; 2 usage error.

patches

• Purpose: View/manage patch stack (applied/reverted).
• Syntax: bpy patches --list [--json]
• Outputs: Patch stack state; JSON for automation.
• Exit codes: 0 success; 1 no patches; 2 error.

undo / redo

• Purpose: Undo applied patch or reapply reverted patch (Git-backed).
• Syntax: bpy undo [--preview] [--json] [--emit-notify]; bpy redo [--preview] [--json] [--emit-notify].
• Outputs: Human text; JSON; JSONL events patch_reverted/patch_applied.
• Exit codes: 0 success; 1 no patch available; 2 Git/error.

Logs / observability hooks

logs

• Purpose: Read/tail BranchPy action logs.
• Syntax: bpy logs [--tail N] [--follow] [--level LEVEL] [--format text|json].
• Paths: %LOCALAPPDATA%/BranchPy/logs/branchpy.log or ~/.local/share/BranchPy/logs/branchpy.log.
• Exit codes: 0 success; 2 file/usage error.

JSONL event emission

• Purpose: Notify VS Code and dashboards of command lifecycle and reports.
• Controls: BRANCHPY_EMIT_NOTIFY=1 for stdout events; BRANCHPY_EMIT_EVENTS=true for stderr prefixed events.
• Schema: See Technical/telemetry/jsonl-events.md and Technical/events/catalog.md.

Future / planned

• serve (planned): local dashboard/webview server. Not shipped; do not rely on.
• cache (planned): telemetry/cache management. Not shipped; do not rely on.

Cross-domain references

• Auth/licensing: Technical/auth-licensing-sso/troubleshooting.md
• Errors taxonomy: Technical/errors/README.md
• Analysis outputs: Technical/analysis/README.md
• Telemetry/events: Technical/telemetry/jsonl-events.md, Technical/events/catalog.md
• Configuration: Technical/cli/configuration.md
• Troubleshooting: Technical/cli/troubleshooting.md