Settings

Global settings control Bivvy’s behavior across all workflows.

Basic Settings

settings:
  defaults:
    output: verbose        # verbose | quiet | silent
  logging: true            # Enable JSONL event logging (default: true)
  log_retention_days: 30   # Max age of log files in days (default: 30)
  log_retention_mb: 500    # Max total size of log files in MB (default: 500)

See Event log for the file location, retention settings, and event format.

Output Modes

Mode	Description
verbose	Show all output (default)
quiet	Show only step names and errors
silent	Show only errors (set via the output: silent config; no equivalent CLI flag)

Override per-run:

bivvy --verbose

bivvy --quiet

The CLI exposes --verbose and --quiet. There is no --silent flag — the silent output mode can only be set in YAML.

Global Environment Variables

Set environment variables for all steps:

settings:
  env:
    RAILS_ENV: development
    DEBUG: "true"

Or load from a file:

settings:
  env_file: .env.bivvy

Both forms can be combined; values in env: win over env_file. These project-wide values are the lowest layer in the env stack — workflow and step values override them, and shell-exported variables override everything. See Environment Variable Precedence.

Custom Secret Patterns

Add extra environment variable names to be masked in all output:

settings:
  secret_env:
    - MY_CUSTOM_SECRET
    - VENDOR_CREDENTIALS

Entries are matched exactly (no wildcards or globbing). For pattern-style matching see the built-in patterns documented in Secret Masking.

Parallel Execution

settings:
  parallel: true      # Enable parallel execution
  max_parallel: 4     # Maximum concurrent steps (default: 4)

When parallel: true, steps without dependencies between them can run concurrently. max_parallel caps how many run at once.

History Retention

settings:
  history_retention: 50  # Keep last 50 runs (default)

Default Rerun Window

default_rerun_window is the project-wide default for how long a successful run keeps a step satisfied. Steps and workflow overrides can opt in to a different window.

settings:
  default_rerun_window: "4h"   # default — accepts duration strings

Accepted values:

Value	Meaning
"4h", "30m", "7d"	Duration string
"0" or "never"	Always treat the step as if it had never run
"forever"	Never re-prompt; the step stays satisfied indefinitely

Diagnostic Funnel

Control the step failure recovery pipeline:

settings:
  diagnostic_funnel: true  # Use diagnostic funnel for failure recovery (default: true)

When enabled, step failures are analyzed by a multi-stage pipeline that produces ranked resolution candidates. When disabled, the legacy pattern registry is used (single fix per error).

Default Environment

Set the environment used when --env is not provided and no environment is auto-detected:

settings:
  default_environment: staging

If omitted, Bivvy falls back to auto-detection and then to development.

Environments

Define custom environments with detection rules, default workflows, and provided requirements:

settings:
  environments:
    staging:
      detect:
        - env: DEPLOY_ENV
          value: staging
      default_workflow: staging
      provided_requirements:
        - postgres-server
        - redis-server

    review_app:
      detect:
        - env: REVIEW_APP
      provided_requirements:
        - docker

Field	Type	Description
detect	list	Environment variable rules for auto-detection
default_workflow	string	Workflow to use when this environment is active
provided_requirements	list	Requirements assumed satisfied (skip gap checks)

Each detect rule checks a single env var. Omit value to match on presence alone.

See Environments for the full guide.

Step Defaults

Set default behavior for all steps:

settings:
  defaults:
    auto_run: true          # Auto-run unsatisfied steps (default: true)
    prompt_on_rerun: false  # Skip satisfied steps silently (default: false)
    rerun_window: "4h"      # How long a successful run counts as satisfied (default: "4h")

See Auto-Run and the Decision Engine for details on how these settings interact.

Auto-Update

Bivvy checks for new versions in the background after each run and installs updates automatically. This is enabled by default.

settings:
  auto_update: true  # Enable automatic background updates (default)

To disable:

settings:
  auto_update: false

This setting is typically placed in the system config (~/.bivvy/config.yml) since it applies to bivvy itself, not to a specific project. You can also toggle it from the command line:

bivvy update --disable-auto-update
bivvy update --enable-auto-update

When disabled, you can still update manually with bivvy update.

See bivvy update for details on how background updates work.