Why Bivvy?

“Set up your bivvy before the mission.”

Every project has a setup script. And every setup script eventually becomes a mess.

The Problem

You’ve seen it. Maybe you wrote it:

#!/bin/bash
# bin/setup - "just run this!"

brew bundle
asdf install
bundle install
yarn install
cp .env.example .env
docker-compose up -d
rails db:create db:migrate db:seed
echo "Done! Maybe. Check the output for errors."

It works. Until it doesn’t.

• No state: Run it twice, it does everything twice
• No recovery: Step 4 fails, you re-run the whole thing
• No visibility: What’s stale? What actually needs to run?
• No sharing: Every project reinvents the same 20 lines
• No help: It failed. Good luck.

What Bivvy Does

Bivvy replaces your setup script with a declarative config and a smart CLI:

.bivvy/config.yml

app_name: myapp

steps:
  brew:
    template: brew-bundle
  ruby:
    template: bundle-install
    check:
      type: change
      target: "Gemfile.lock"
  node:
    template: yarn-install
    check:
      type: change
      target: "yarn.lock"
  docker:
    template: docker-compose-up
  db:
    command: "rails db:prepare"
    depends_on: [docker]

workflows:
  default:
    steps: [brew, ruby, node, docker, db]

Then:

bivvy run

bivvy status

What Makes Bivvy Different

1. State Tracking

Bivvy remembers what’s done.

  ⛺ myapp — Status

  Environment: development (default)

  Last activity: 2 hours ago

  Steps:
    ✓ brew                 2h ago
    ⚠ ruby                 stale
    ✓ node                 2h ago
    ✓ docker               2h ago
    ◌ db                   never run

Run bivvy run and it only runs what’s needed.

2. Watch Files

ruby:
  template: bundle-install
  check:
    type: change
    target: "Gemfile.lock"

Changed Gemfile.lock? Ruby step is stale. Didn’t change it? Skip.

No more “just run the whole script to be safe.”

3. Error Recovery

Step fails? Bivvy doesn’t just dump you back to the terminal:

✗ ruby failed: bundle install exited 1

How do you want to proceed?
  [r] Retry     - run the step again
  [f] Fix       - bundle update nokogiri
  [s] Skip      - continue without this step
  [x] Shell     - drop to shell to debug
  [q] Abort     - stop the workflow

Context-aware suggestions. Real options. Not “figure it out yourself.”

4. Template Registry

Stop copying the same setup logic between projects:

# Your config just references templates
steps:
  ruby:
    template: bundle-install

Templates are reusable, shareable, and overridable. Bivvy ships with common ones. You can add your own. Teams can share them.

5. Remote Sources for Teams

Central team control, distributed execution:

template_sources:
  - name: company
    type: git
    url: git@github.com:mycompany/bivvy-templates.git

steps:
  ruby:
    template: company:ruby/standard  # Team-managed template

Platform team updates the template. Every project gets the update. No more copy-paste drift.

6. CI-Aware Output

In an interactive terminal, Bivvy renders progress with spinners, color, and a recovery menu when steps fail.

In a CI pipeline, it auto-detects non-interactive environments (CI, GITHUB_ACTIONS, etc.) and switches to clean line-based output with non-zero exit codes — no progress bars to clutter logs. You can force it either way with --non-interactive (or, equivalently, --env ci).

How Bivvy Compares

Tool	What It Does	What’s Missing
bin/setup	Runs commands	No state, no recovery, no reuse
Make/Task	Runs commands with dependencies	No state tracking, no watch files, no templates
mise/asdf	Manages runtime versions	Doesn’t orchestrate setup steps
Docker	Containerized environments	Different paradigm - containers, not local setup
Nix/devenv	Hermetic reproducibility	Steep learning curve, replaces your whole toolchain

Bivvy’s lane: Orchestrate your existing tools (brew, bundle, yarn, docker) with state tracking, smart re-runs, and good UX.

Bivvy vs. Nix

This comes up a lot. Here’s the sharp distinction:

• Nix = “I want mathematically reproducible environments”
• Bivvy = “I want my setup script to be smarter”

Nix is the right choice if you need hermetic builds where every byte is identical across machines.

Bivvy is the right choice if you need:

• Setup that remembers what it did
• Re-runs that only do what’s necessary
• Error recovery that helps instead of abandons
• Templates your team can share

Most teams don’t need Nix-level reproducibility. They need “run bundle install if Gemfile.lock changed, and if it fails, let me retry or drop to a shell.”

That’s bivvy.

Who It’s For

Individual devs who:

• Work on multiple projects with similar stacks
• Are tired of re-running full setup scripts “just in case”
• Want to know what’s stale without reading the script

Teams who:

• Onboard new devs regularly
• Want consistent setup across projects
• Need central control of setup standards
• Have flaky steps that need retry logic

Platform engineers who:

• Maintain setup templates for the org
• Want to push updates without touching every repo
• Need visibility into what projects are running

Getting Started

Install (pick one):

curl -fsSL https://bivvy.dev/install | sh

brew install https://raw.githubusercontent.com/bivvy-dev/bivvy/main/dist/homebrew/bivvy.rb

cargo install bivvy

gem install bivvy

pip install bivvy

Initialize in your project:

bivvy init

Run setup:

bivvy run

Check status anytime:

bivvy status

See Installation docs for details on each method.

The Name

A bivvy (or bivouac) is a temporary camp set up quickly before a mission. That’s what dev environment setup should be: fast, reliable, and out of your way so you can focus on the actual work.

Set up your bivvy. Get to work.