Commands
Every command. Global resolution: the store is --store → BOCAL_STORE → bocal.toml store → .bocal; the registry is --registry → BOCAL_REGISTRY → default.
Exit codes: 0 success, 1 generic error, 3 blocking engine-version incompatibility, 4 lock timeout.
init
bocal init [--store <path>]
Create bocal.toml in the current directory with defaults and add .bocal/ + .bocal.env to .gitignore. bocal.toml is meant to be committed (it holds the store path and shared registry config, no secrets); the store and .bocal.env are not.
save
bocal save <name> [--tag <tag>] [--store <path>] [--services <a,b,c>]
[--port <service>=<port>] [--host <service>=<host>]
[--worktree <path>] [--from-env <file>] [--force]
Capture the current environment state into a fixture tag. Reads the existing tag's fixture.toml to learn which services/files/env to capture (bocal does not auto-discover).
- Atomic: writes into a temp dir, then renames over the target tag only after every service succeeds. A failed save never corrupts an existing tag.
- Writes
manifest.json(per-file SHA-256) at save time, soverifyworks even on fixtures that were never pushed. --tagdefaults tolatest. Explicit tags are immutable (need--forceto overwrite).--services(re)captures only the listed services; the others are carried forward from the existing tag unchanged, and a warning lists them with their originalcaptured_at. Unknown service names are rejected.--port/--hostoverride resolution for one service (repeatable).--from-env <file>merges aKEY=valuefile into[env](see parsing rules).savenever needs--allow-remote— reading from a remote host is non-destructive.
restore
bocal restore <name> [--tag <tag>] [--store <path>] [--services <a,b,c>]
[--port <service>=<port>] [--host <service>=<host>] [--allow-remote]
[--worktree <path>] [--env-out <file>] [--no-env] [--no-files]
[--dry-run] [--yes] [--pull] [--registry <name>] [--ci]
[--backup] [--undo]
Restore a fixture into the current environment. This is the most destructive command bocal has — it overwrites live databases and worktree files, and it is not transactional.
Preflight (always runs, before any write) verifies the whole plan and aborts as a group if anything fails:
- The tag exists,
fixture.tomlparses, every declared service's dump is present. - Each engine's required tooling is on
PATH. - Each service's host/port resolves and the target is reachable; for built-in engines, the target database exists and is connectable.
- Non-loopback guard: any service resolving to a non-loopback host aborts unless
--allow-remoteis passed (not implied by--yes). - Engine version compatibility (see Engines): a blocking error for known-incompatible pairs, a warning otherwise.
[[files]]dst paths resolve inside the worktree;[env]{{ }}placeholders all resolve (an unresolved one is a hard error).
If preflight passes, bocal prints the plan and prompts for confirmation unless --yes. --dry-run prints the plan and exits without restoring or prompting.
Then, in declared order: restore each service's dump, write [env] (placeholders substituted) to the env file, and copy [[files]] into the worktree (directory entries merge; nothing is deleted).
Flags:
| Flag | Effect |
|---|---|
--no-env / --no-files | Skip writing the env file / copying files. |
--services | Restore only the listed services (unknown names rejected). |
--dry-run | Preflight + plan, then exit. No prompt, no mutation. |
--yes | Skip the confirmation prompt (hooks/CI). Does not imply --allow-remote. |
--host / --allow-remote | Override host; permit a non-loopback target. |
--pull | Pull the tag from the registry first (keeps the store), then restore. Errors on a diverged local tag. |
--registry <name> | Registry for --pull/--ci. |
--ci | Restore directly from the registry into a throwaway temp dir (no store). Implies --yes. Mutually exclusive with --pull. |
--backup | Dump each target to a sidecar undo set (<store>/.undo/) before overwriting. |
--undo | Reload the most recent undo set back into the targets (itself runs preflight). Mutually exclusive with --backup. |
Not transactional. A mid-sequence failure leaves earlier services already restored, and a failed
pg_restore --cleancan leave a database with objects dropped but not recreated. Recovery: re-run after fixing the cause, or (if you ran with--backup)--undo.
ls
bocal ls [--store <path>] [--json]
List all fixtures in the store, one row per tag (name, tag, services, created-at, description).
rm
bocal rm <name> [--tag <tag>] [--store <path>] [--yes]
Delete a fixture or a specific tag from the local store. Without --tag, deletes the whole fixture. Prompts unless --yes. Never touches the registry (use registry rm for that).
diff
bocal diff <a>[:<tag>] <b>[:<tag>] [--store <path>] [--no-env] [--no-files]
Compare two local fixtures (or two tags), from local data only. Reports an [env] key diff, an [[files]] diff (by SHA-256 hashed from disk), and a lightweight per-service dump comparison: identical on a checksum match, else a size delta. See Registry for the contrast with registry diff.
push
bocal push <name> [--tag <tag>] [--registry <name>] [--store <path>]
Upload a fixture tag to the registry — fixture.toml + dumps + files, with manifest.json written last (so a half-completed push has no manifest and is ignored by readers). Large files use multipart upload.
pull
bocal pull <name> [--tag <tag>] [--registry <name>] [--store <path>] [--force]
Download a fixture tag into the local store. Skips files whose local SHA-256 already matches. Without --force, errors if a local tag exists and differs (by checksum), showing local vs remote provenance; --force overwrites.
verify
bocal verify <name> [--tag <tag>] [--store <path>]
Local integrity check (no registry contact): fixture.toml parses, every dump is present, and each file's SHA-256 matches manifest.json. Also surfaces the divergence advisory. Without --tag, verifies all tags.
registry subcommands
Manage registries (like git remotes) and operate on a registry's contents.
bocal registry add <name> <bucket> [--region <r>] [--endpoint <url>] [--prefix <p>]
[--path-style] [--profile <p>] [--global] [--force]
bocal registry remove <name> [--global]
bocal registry remotes [--json]
bocal registry ls [--registry <name>] [--json]
bocal registry diff <name> [--tag <tag>] [--registry <name>]
bocal registry rm <name> [--tag <tag>] [--registry <name>] [--yes]
add— write a[registries.<name>]block (validated with a liveHeadBucket).--globalwrites~/.config/bocal/config.toml. Records the profile name only; never a secret.remove— delete a registry block from config. (Contrastrm, which deletes fixtures from the bucket.)remotes— list configured registries (git remote -v), marking the default with*.ls— list the fixtures inside a registry's bucket.diff— compare a local tag vs the remote (by checksum).rm— delete a fixture or tag from the registry (manifest deleted first). Louder confirmation — it removes it for everyone.