BranchPy
Se connecter

CLI Configuration

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.

How the CLI reads settings, honors environment variables, and writes outputs.

Config files and precedence

  1. Command-line flags (highest): --config <file>, --format, --json, --project/-p, --verbose/--quiet, --no-color.
  2. Project config: .branchpy.toml in project root.
  3. User config: %LOCALAPPDATA%/BranchPy/config.toml (Windows) or ~/.local/share/BranchPy/config.toml (macOS/Linux).
  4. Built-in defaults (lowest).

Config files are TOML. Parse errors surface as exit code 3 (configuration error). See Technical/errors/README.md.

Environment variables

  • BRANCHPY_DEBUG: true/1 enables debug logging.
  • BRANCHPY_CONFIG: override config file path.
  • BRANCHPY_NO_COLOR: disable ANSI color output.
  • BRANCHPY_LOG_LEVEL: debug|info|warn|error for CLI logging.
  • BRANCHPY_CACHE_DIR: override cache directory (default user cache).
  • BRANCHPY_EMIT_NOTIFY: 1/true/on to emit JSONL events on stdout (VS Code integration).
  • BRANCHPY_EMIT_EVENTS: true to emit internal events on stderr with BRANCHPY_EVENT: prefix.
  • BRANCHPY_CAPTURE_CLI (extension): when enabled, VS Code listens for JSONL notifications.

Global flags behavior

  • --json implies --format json when not explicitly set.
  • --format text|json|html selects serializer for report-bearing commands.
  • --project/-p sets project root; also used to resolve .branchpy/ paths.
  • --no-color disables ANSI colors even when terminal supports them.
  • --verbose increases detail; --quiet suppresses non-essential output (errors still printed).

Output locations

All CLI outputs are written inside a .branchpy/ folder at the root of your project. The table below lists every subfolder and file, what creates it, and whether it is safe to delete.

Path (relative to project root) Created by Safe to delete?
.branchpy/analyze/ branchpy analyze Yes � recreated on next run
.branchpy/cache/ branchpy analyze --format json Yes � recreated on next run
.branchpy/stats/ branchpy stats Yes � recreated on next run
.branchpy/reports/ branchpy analyze Yes � recreated on next run
.branchpy/media/ branchpy media Yes � recreated on next run
.branchpy/pilot/ branchpy pilot Yes � recreated on next run
.branchpy/index/ branchpy analyze (LMDB index) Yes � re-indexed on next run
.branchpy/logs/ Any CLI command Yes � new log file created on next run
.branchpy/runner_cache/ VS Code runner Yes � recreated on next runner execution
.branchpy/patches/ branchpy guard Yes � recreated on next guard run
.branchpy/omega/ VS Code Omega panel Yes � recreated on next Omega run
.branchpy/out/ Legacy fallback (pre-1.1.17) Yes � no longer the canonical location
.branchpy/insight_summary.json branchpy analyze Yes � recreated on next analyze run

Do not delete these files:

File Why
.branchpy/config.toml Project configuration (game path, project name, engine type). Deleting it loses your project binding � the VS Code extension will prompt for project selection again and commands will fail until reconfigured.
.branchpy/install_id Ties telemetry to this installation. Deleting it generates a new anonymous ID; historical telemetry becomes orphaned.
  • Logs: %LOCALAPPDATA%/BranchPy/logs/branchpy.log or ~/.local/share/BranchPy/logs/branchpy.log.
  • SDK registry and pins: .branchpy.toml (project) and user config.
  • JSONL events: stdout/stderr when emit toggles are set; consumers must ignore non-JSON lines.

Formats and schemas