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.
bocalis 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
customengine). - Config files — copied into your worktree on restore.
- Environment variables — written to a plain
KEY=valuefile (.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.
restoreruns a preflight (dumps present, tooling onPATH, target reachable and the database exists, engine versions compatible) before touching anything, then prompts for confirmation likerm. It supports--dry-run,--backup/--undo, and a non-loopback--allow-remoteguard. - Honest about guarantees. A multi-service fixture is not a coordinated point-in-time snapshot; bocal records a per-service
captured_atand warns on divergence rather than hiding it. - Extensible without forking. Postgres and MySQL are first-class; everything else works today via the
customengine (pointsave/restoreat 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.