BranchPy
Log in

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

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

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