Configuration

Bivvy uses YAML configuration files to define your project setup.

File Locations

Configuration is loaded and merged in this order (later overrides earlier):

Remote base configs (from extends:)
User global config (~/.bivvy/config.yml)
Project config (.bivvy/config.yml)
Split-file step definitions (.bivvy/steps/*.yml)
Workflow file for the active workflow (.bivvy/workflows/<name>.yml)
Local overrides (.bivvy/config.local.yml) — gitignored

On the first invocation, Bivvy creates ~/.bivvy/config.yml automatically if it doesn’t already exist. The seeded file contains commented-out examples of the supported settings: keys to make global options discoverable. Edit it to enable machine-wide defaults, or delete it freely — Bivvy will recreate it (with only the commented examples) on the next run, and existing content is never overwritten.

When bivvy run <workflow> executes, only the workflow file matching the requested name participates in the merge. Other workflow files in .bivvy/workflows/ are not parsed, so a broken sibling cannot prevent an unrelated workflow from running. See Portable Workflow Files for the full layout.

`extends:`

The top-level extends: key lets a config inherit from one or more remote base configs. Each entry is fetched, parsed, and merged before the rest of the local file is applied — so anything you declare locally still wins. URLs must be trusted on first use (or globally with --trust).

extends:
  - url: https://example.com/team-base.yml

`template_sources:`

template_sources: registers additional remote registries that contribute step templates beyond the built-in registry. Each entry points to a URL and (optionally) configures cache behavior, priority, timeout, and authentication. Templates from registered sources can be referenced by name from any step’s template: field; multiple sources are tried in priority order (lower number = higher priority). See Templates: Remote Sources for the full schema.

Basic Structure

app_name: "MyApp"

settings:
  defaults:
    output: verbose  # verbose | quiet | silent

steps:
  install_deps:
    command: "npm install"

workflows:
  default:
    steps: [install_deps]

Variable Interpolation

Use ${VAR} syntax to interpolate values:

steps:
  setup:
    command: "echo Setting up ${project_name}"

Resolution Priority

Variables are resolved in this order (highest to lowest):

Prompt values from the current run
Saved preferences from previous runs
User-defined variables (vars:)
Template inputs (the resolved inputs: map for the current step)
Environment variables
Built-in variables

Built-in Variables

Variable	Description
`${project_name}`	Directory name of the project
`${project_root}`	Absolute path to project root
`${bivvy_version}`	Current Bivvy version

User-Defined Variables

Define reusable values — static strings or shell commands — under the top-level vars: key. See Variables for details.

vars:
  version:
    command: "cat VERSION"

steps:
  tag:
    command: "git tag v${version}"

Environment Variables

Environment variables are available for interpolation:

steps:
  deploy:
    command: "deploy --env ${RAILS_ENV}"

Escaping

Use $${ to escape (outputs literal ${):

steps:
  example:
    command: "echo '$${NOT_INTERPOLATED}'"  # outputs: ${NOT_INTERPOLATED}

Deep Merge Behavior

When multiple config files define the same key:

Objects: Recursively merged (nested keys combined)
Arrays: Replaced entirely (not concatenated)
Scalars: Later value wins

steps:
  deps:
    command: "yarn install"
    env:
      NODE_ENV: development

# .bivvy/config.local.yml
steps:
  deps:
    env:
      NODE_ENV: production
      # command is preserved from base