BranchPy
Log in

CLI Quick Reference

Core commands

Command Purpose
branchpy --project <path> analyze Full project analysis
branchpy --project <path> flowchart --open Open Flowchart viewer from latest analysis
branchpy --project <path> stats --open Open stats and metrics view
branchpy --project <path> media --open Run Media Validation and open results
branchpy --project <path> doctor --json Environment and setup diagnostics
branchpy compare --old <src> --new <src> --json Compare two reports/runs

Utility and platform commands

  • Getting started: help, version, update, guard
  • Project / SDK: renpy detect|list|add|remove|use|default|validate, config init|show|get|set|unset|list
  • Analysis/reporting: tests, report list|show|export|clean
  • History and patches: history undo|redo|show|clear, patches, undo, redo
  • Logs and observability: logs --tail N --follow

Global flags cheat sheet

  • --project/-p <path>: set project root.
  • --format text|json|html: choose output serializer.
  • --json: shorthand for --format json.
  • --no-color: disable ANSI colors.
  • --verbose / --quiet: adjust verbosity.
  • --config <file>: override config path.

Exit codes

  • 0: success.
  • 1: issues found (validation/analysis/policy).
  • 2: command/usage/runtime error.
  • 3: configuration error (parse/permission).
  • 4: environment error.
  • 5: SDK error.
  • 10: doctor internal error. See Technical/errors/README.md for taxonomy.

Environment variables

  • BRANCHPY_DEBUG: enable debug logging.
  • BRANCHPY_CONFIG: config file path override.
  • BRANCHPY_NO_COLOR: disable colors.
  • BRANCHPY_LOG_LEVEL: log level.
  • BRANCHPY_CACHE_DIR: cache directory override.
  • BRANCHPY_EMIT_NOTIFY: emit JSONL on stdout.
  • BRANCHPY_EMIT_EVENTS: emit internal events on stderr.
  • BRANCHPY_CAPTURE_CLI: VS Code extension capture toggle.

Common workflows

  • Baseline analysis and save report:
    • branchpy --project <project> analyze --save-report --format json
  • Matrix compatibility across SDKs:
    • branchpy renpy detect -> branchpy tests --matrix sdk-8.1.3,sdk-8.2.0,latest --save-report
  • Compare changes between runs:
    • branchpy compare --old last-1 --new last --format json
  • Diagnose environment before CI:
    • branchpy --project <project> doctor --json
  • Fix SDK registry then retest:
    • branchpy renpy validate --fix -> branchpy tests --matrix ...
  • Patch safety net:
    • branchpy undo --preview -> branchpy undo (apply) -> branchpy redo if needed
  • Media hygiene sweep:
    • branchpy --project <project> media --missing --json -> fix assets -> branchpy --project <project> media --unused
  • VS Code integration notifications:
    • Set BRANCHPY_EMIT_NOTIFY=1 -> run branchpy tests --emit-notify