BranchPy
Se connecter

Feature Run Modes (VS Code + CLI)

Excusez-nous — cette page est actuellement disponible en anglais uniquement.

La traduction française n'est pas encore prête. Le contenu ci-dessous est la version anglaise la plus récente.

This page standardizes how each BranchPy feature is documented:

  • Feature description: what it is, what you can see/analyze, and why it matters.
  • VS Code path: how to run it from BranchPy Control Center.
  • CLI path: command syntax with all stable options.

Use this as the practical bridge between the User Guide and the CLI canon.

This page is a companion reference, not a replacement for feature pages.

Last updated: v1.1.17 — added Guard, Insights, Identity, and Export Media command paths.

Analyze

Feature description

Analyze is the full project pass. It builds diagnostics and flow data so you can identify breakage, dead paths, and regressions early.

Run in VS Code (BranchPy Control Center)

  1. Open BranchPy Control Center.
  2. Select Analyze.
  3. Choose project root if prompted.
  4. Run and review issues, counts, and report links.

Run via CLI (all stable options)

branchpy --project <path> analyze [--format text|json|html] [--save-report] [--matrix <sdks>] [--assets] [--out <dir>] [--emit-notify] [--json]

Full reference: /docs/v1.2/technical/cli/cli/

Stats

Feature description

Stats summarizes project health and structure metrics. Use it to track trends and verify whether quality is improving over time.

Run in VS Code (BranchPy Control Center)

  1. Open Stats from Control Center.
  2. Select the run/report context.
  3. Review totals and trend indicators.

Run via CLI (all stable options)

branchpy --project <path> stats [--format text|json|html] [--save] [--out <dir>]

Full reference: /docs/v1.2/technical/cli/cli/

Compare

Feature description

Compare highlights differences between two runs/reports. Use it for release checks, regression triage, and branch validation.

Run in VS Code (BranchPy Control Center)

  1. Open Compare.
  2. Select old and new runs.
  3. Review added/removed/changed issues.

Run via CLI (all stable options)

branchpy compare --old <source> --new <source> [--format text|json] [--changes-only] [--out <path>]

Full reference: /docs/v1.2/technical/cli/cli/

Doctor

Feature description

Doctor checks environment and config readiness. Use it when runs fail unexpectedly or before CI gating.

Run in VS Code (BranchPy Control Center)

  1. Open Doctor.
  2. Run diagnostics.
  3. Apply suggested fixes and re-run.

Run via CLI (all stable options)

branchpy --project <path> doctor [--verbose] [--json] [--emit-notify]

--project is the global flag, not a Doctor-specific argument. Full reference: /docs/v1.2/technical/cli/cli/

Image Validation

Feature description

Image Validation audits image quality and consistency across your project — resolution spread, naming convention splits (underscores vs hyphens), and exact duplicate detection. Use it before release or after importing new art assets.

Run in VS Code (BranchPy Control Center)

  1. Open BranchPy Control Center.
  2. Run Analyze at least once.
  3. Open Image Validation from the Control Center or the BranchPy command palette.

The panel scans automatically on open. No configuration required.

Run via CLI (all stable options)

# Human-readable summary
branchpy --project <path> image-validate

# JSON output for scripting or VS Code panel
branchpy --project <path> image-validate --json

# Write standalone HTML report to .branchpy/reports/image-validation.html
branchpy --project <path> image-validate --html

# Write HTML report and open immediately in browser
branchpy --project <path> image-validate --open

Options: --engine <renpy|unity|godot|unreal|generic> (default: renpy), --include-gui (include engine GUI assets).

Full reference: /docs/v1.2/technical/cli/cli/

Media Validation

Feature description

Media Validation audits asset usage and hygiene (missing, unused, invalid media). Use it to clean media debt and reduce runtime failures.

Run in VS Code (BranchPy Control Center)

  1. Open Media Validation.
  2. Run scan.
  3. Filter and inspect findings.

Run via CLI (all stable options)

branchpy --project <path> media [--missing|--unused|--validate|--optimize] [--assets <path>] [--ext <list>] [--recursive] [--json]

Full reference: /docs/v1.2/technical/cli/cli/

Patch Timeline

Feature description

Patch Timeline shows reversible operation history so you can understand what changed and when.

Run in VS Code (BranchPy Control Center)

  1. Open Patch Timeline.
  2. Browse entries.
  3. Use Undo/Redo controls where available.

Run via CLI (all stable options)

branchpy history show [--limit <N>] [--json]
branchpy history undo [STEPS] [--json] [--emit-notify]
branchpy history redo [STEPS] [--json] [--emit-notify]
branchpy patches --list [--json]
branchpy undo [--preview] [--json] [--emit-notify]
branchpy redo [--preview] [--json] [--emit-notify]

Full reference: /docs/v1.2/technical/cli/cli/

Flowchart

Feature description

Flowchart is the standalone visual browser for the analysis graph produced by Analyze. Use it to validate reachability, branch shape, and dead-end patterns.

Run in VS Code (BranchPy Control Center)

  1. Run Analyze first.
  2. Open Flowchart from the completed Analyze run.
  3. Inspect nodes, edges, and details.

Run via CLI (all stable options)

branchpy --project <path> analyze --open
branchpy --project <path> flowchart --open

Optional export:

branchpy --project <path> flowchart --out <file>.html

Reference: /docs/v1.2/technical/analysis/cfg/

FlowchartPlus

FlowchartPlus has no standalone CLI command. It activates automatically in the VS Code Control Center when the required reports are present: Analyze (with D9 Narrative Analysis), Pilot, and Omega. There is no branchpy flowchart-plus command.

To prepare the data for FlowchartPlus from CLI:

branchpy --project <path> analyze
branchpy --project <path> pilot
branchpy omega --project-root <path>

Then open FlowchartPlus from the Control Center. See FlowchartPlus for gating states and layout mode detail.

Governance

Feature description

Governance surfaces policy and audit posture so teams can enforce standards before merge/release.

Run in VS Code (BranchPy Control Center)

From Control Center:

  1. Open Governance panel.
  2. Review status and policy findings.
  3. Export/share evidence as needed.

From Command Palette (Ctrl+Shift+P):

  • BranchPy: Run Guard — runs branchpy guard for the current project. If the project has not been initialized (branchpy guard init), an Initialize Guard dialog appears before running.

Run via CLI (all stable options)

branchpy guard [--json] [--project <path>] [--config <file>] [--verbose] [--quiet] [--no-color]

Reference: /docs/v1.2/technical/cli/cli/

Watch

Feature description

Watch is continuous feedback while editing.

Run in VS Code (BranchPy Control Center)

  1. Open Watch mode from Control Center.
  2. Start watch session.
  3. Review triggered reruns.

Run via CLI

No dedicated stable watch command is documented in v1.1.1 CLI canon. Use Analyze/Stats/Compare commands explicitly in scripts or CI.

Pilot

Feature description

Pilot is a path-aware variable analysis pass. It enumerates execution paths from the CFG built by Analyze and tracks variable timelines across those paths.

Run in VS Code (BranchPy Control Center)

  1. Run Analyze first.
  2. Open Pilot.
  3. Review paths, variable chips, and early warnings.
  4. Follow with Analyze before release decisions.

Run via CLI (all stable options)

branchpy --project <path> pilot [--max-paths <N>] [--max-depth <N>]

Requires a prior Analyze run. Advanced command — behavior may evolve between minor versions.

Function Manager

Feature description

Function Manager discovers, indexes, and checks all custom functions in the project. Includes stat effect analysis, call graph, and consistency checks (dead/shadowed/duplicate functions).

Run in VS Code (BranchPy Control Center)

  1. Open Function Manager.
  2. Filter by stat modifiers, unused, or redefined functions.
  3. Navigate to definition via click.

Run via CLI (all stable options)

branchpy pfi -p <path> [--format full|compact|by-stat] [--show-warnings] [--show-dead] [--show-call-graph] [--export-dot <file>] [--output <file>]

Alternatively, add function analysis to any Analyze run:

branchpy --project <path> analyze --export-functions

Full reference: /docs/v1.2/technical/analysis/pfi/

Account and License

Feature description

Account/License controls sign-in state and entitlement.

Run in VS Code (BranchPy Control Center)

  1. Open Account or License settings.
  2. Sign in.
  3. Validate active license/claim state.

Run via CLI (license command family)

branchpy license login
branchpy license status
branchpy license claim-renpy

Settings (General and Subsections)

Feature description

Settings control project roots, SDK mappings, telemetry behavior, and operational defaults.

Run in VS Code (BranchPy Control Center)

  1. Open Settings.
  2. Change only required keys.
  3. Re-run Analyze after impactful config changes.

Run via CLI (all stable options)

branchpy config <init|show|get|set|unset|list> [--project <path>] [--json]
branchpy renpy <detect|list|add|remove|use|default|validate> [options]

CLI reference: /docs/v1.2/technical/cli/configuration/

Insights

Feature description

Insights summarizes narrative and structural health in plain language after an analysis run. It reads insight_summary.json and presents five sections: story health, variable health, complexity score, state space, and asset coverage.

Run in VS Code (Command Palette)

Ctrl+Shift+P → BranchPy: Show Insights

Opens the Insights panel directly from the last analysis output. Requires a prior Analyze run (.branchpy/insight_summary.json must exist).

Run via CLI

Insights are generated automatically at the end of every full Analyze run. No separate CLI command.

branchpy --project <path> analyze   # insight_summary.json is written to .branchpy/

Identity (whoami)

Feature description

Shows who is currently logged into BranchPy in VS Code — username, email, plan, status, and session timestamp. Reads the extension’s own login state (same source as the Control Center Account section).

Run in VS Code (Command Palette)

Ctrl+Shift+P → BranchPy: Show Identity

Displays a VS Code notification with the logged-in user’s details. If you see “Not logged in”, open the Control Center, go to the Account section, and sign in.

Run via CLI

branchpy whoami

The CLI whoami reads ~/.branchpy/identity/session.json, which is a separate session from the VS Code login. Use the VS Code command to check your VS Code login state.

Export Media

Feature description

Export Media writes a structured file listing all media references found in the project — image and audio files that scripts reference. Use it for asset audits, handoff documents, or CI pipelines.

Run in VS Code (Command Palette)

Ctrl+Shift+P → BranchPy: Export Media References

  1. Choose output format: CSV or JSON.
  2. Pick a save location via the Save dialog.
  3. The file is written; a notification confirms the path.

Requires a prior Analyze run (.branchpy/reports/unified/unified_report.json must exist).

Run via CLI (all stable options)

branchpy --project <path> export-media [--format csv|json] [--out <file>] [--report <report-file>]

Default report input: .branchpy/reports/unified/unified_report.json

Notes

  • Use --project <path> explicitly in automation for deterministic behavior.
  • For machine-readable workflows, prefer --json and stable JSON/JSONL outputs.
  • UI may expose feature previews before a stable dedicated CLI command exists.