bocal

bocal is a CLI for capturing and restoring named environment snapshots. A snapshot bundles together database dumps, config-file overrides, and environment-variable overrides into a named, versioned artifact called a fixture. Fixtures can be saved locally, shared with a team via an S3-compatible registry, and restored into any environment — with or without an orchestrator.

bocal is French for jar — the sealing jar you preserve things in.

I like my env  →  bocal save  →  bocal push  →  teammate: bocal pull  →  bocal restore

The problem

Reproducing a specific application state — a particular customer's data, a regression case, a feature scenario — usually means one of:

  • Seed scripts that are slow, fragile, and drift from real data.
  • Manual database dumps with no versioning or sharing.
  • Every developer maintaining their own local setup with no way to share it.

It gets worse with multiple databases (say Postgres + Dolt), config files that must change alongside the data, and env vars that differ per scenario. There is no standard tool for capturing and restoring a complete environment state as a unit.

What bocal does

A fixture packages three things together:

  • Database dumps — one per service (Postgres, MySQL/Dolt, or anything via a custom engine).
  • Config files — copied into your worktree on restore.
  • Environment variables — written to a plain KEY=value file (.bocal.env) on restore.

Two commands do the real work:

bocal save customer-a       # capture current DB + files + env into a fixture
bocal restore customer-a    # blow that state back into your environment

Plus versioning with tags (latest is the default) and team sharing via an S3-compatible registry (push / pull).

Design philosophy

  • No opinion about your environment. bocal never starts, stops, or manages services. It speaks in ports, files, and env vars — tell it where the database is listening and where your worktree is, and it works. This is why it composes with an orchestrator like ecluse purely by convention, with zero orchestrator-specific code.
  • Safety-first on the destructive path. restore runs a preflight (dumps present, tooling on PATH, target reachable and the database exists, engine versions compatible) before touching anything, then prompts for confirmation like rm. It supports --dry-run, --backup/--undo, and a non-loopback --allow-remote guard.
  • Honest about guarantees. A multi-service fixture is not a coordinated point-in-time snapshot; bocal records a per-service captured_at and warns on divergence rather than hiding it.
  • Extensible without forking. Postgres and MySQL are first-class; everything else works today via the custom engine (point save/restore at shell commands).

Where to go next

  • Install — get the binary.
  • Quickstart — save and restore in a few commands.
  • Concepts — fixtures, tags, stores, registries.
  • Commands — the full CLI reference.