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, so verify works even on fixtures that were never pushed.
  • --tag defaults to latest. Explicit tags are immutable (need --force to 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 original captured_at. Unknown service names are rejected.
  • --port/--host override resolution for one service (repeatable).
  • --from-env <file> merges a KEY=value file into [env] (see parsing rules).
  • save never 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.toml parses, 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-remote is 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:

FlagEffect
--no-env / --no-filesSkip writing the env file / copying files.
--servicesRestore only the listed services (unknown names rejected).
--dry-runPreflight + plan, then exit. No prompt, no mutation.
--yesSkip the confirmation prompt (hooks/CI). Does not imply --allow-remote.
--host / --allow-remoteOverride host; permit a non-loopback target.
--pullPull the tag from the registry first (keeps the store), then restore. Errors on a diverged local tag.
--registry <name>Registry for --pull/--ci.
--ciRestore directly from the registry into a throwaway temp dir (no store). Implies --yes. Mutually exclusive with --pull.
--backupDump each target to a sidecar undo set (<store>/.undo/) before overwriting.
--undoReload 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 --clean can 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 live HeadBucket). --global writes ~/.config/bocal/config.toml. Records the profile name only; never a secret.
  • remove — delete a registry block from config. (Contrast rm, 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.