Back up a Busabase space to a single portable archive, and restore it — full history, original ids, real files — with busabase-cli backup and restore.

Backup & Restore

busabase-cli backup exports a whole Busabase space — every node, base, record, field value, doc body, uploaded file, and (optionally) its full Change Request / commit history — into one portable .bbdump archive. busabase-cli restore puts it back. Use it for disaster recovery, moving a space between a local self-hosted instance and Cloud, or keeping an offline snapshot before a risky change.

This page previously documented a separate busabase-dump CLI, with the commands spelled busabase-dump export / busabase-dump import. That tool was never released; the workflow ships inside busabase-cli instead, so there is one tool, one login, and one config file. Install it with npm i -g busabase-cli.

Install and run

npx busabase-cli backup
npx busabase-cli restore space.bbdump

No separate config step needed if ~/.busabase/.env already has a base URL, API key, and space id — the same file busabase-cli login writes. If you've already connected an agent (see Bring Your Own Agent), backup works with zero extra setup.

Back up a space

npx busabase-cli backup -o space.bbdump

This walks every table in the space — nodes, bases/fields/views, records and field values, record links, assets and their uploaded bytes, doc bodies, and (by default) the full commit/Change Request/review/audit history — and writes it into a single .bbdump file (a streaming tar archive, zstd-compressed).

Flag	Effect
`-o, --out-file <file>`	Output archive path (default `space.bbdump`)
`--no-history`	Skip commits/Change Requests/operations/comments/reviews/audit events — keep only current state
`--space-id <id>`	Which space to back up (default: `BUSABASE_SPACE_ID` / `~/.busabase/.env`)

Vault secrets and webhook signing keys are never included in a backup — a .bbdump archive is safe to store or transfer without leaking credentials.

Restore into a space

npx busabase-cli restore space.bbdump

Restoring is full-fidelity: every node, base, record, and history entry comes back with its original id, so links and references between records stay intact. Because of that, the target space must be genuinely empty (only the auto-created workspace root) — restore refuses to write into a space that already has content, so it never silently merges into or overwrites existing work.

After every table is written, restore runs an integrity pass and reports any orphaned reference (a field value pointing at a field that was never restored, a record link with a missing endpoint, a file whose bytes never made it into storage) as a warning, so you know exactly what to check before trusting the restored space.

Choosing where to restore

Point --base-url / --space-id at wherever you want the copy to land — a different space on the same server, a different self-hosted instance, or a Cloud workspace:

npx busabase-cli restore space.bbdump \
  --base-url https://busabase.com \
  --api-key <token> \
  --space-id <target-space-id>

Backup vs. export — which one do I want?

Two different jobs, two deliberately different formats:

	`backup` / `restore`	`export` / `install`
Format	One compressed `.bbdump` archive	A readable, diffable directory tree you can push to GitHub
Carries	Everything: raw rows, original ids, history, comments, reviews, audit events, permissions	Current state only — the content, not its past
Target space	Must be empty	Installs into an existing space, alongside what's there
Ids	Preserved exactly	Fresh ids on install
Use it for	Disaster recovery, moving a whole space	Sharing a template, versioning content in git

If you want "give someone a copy of this base to start from", you want export. If you want "if the server burns down I can rebuild this space exactly", you want backup.

Configuration

Same precedence as every other Busabase client:

What	Flag	Env var	Saved in
Host	`--base-url <url>`	`BUSABASE_BASE_URL`	`~/.busabase/.env`
API key	`--api-key <token>`	`BUSABASE_API_KEY`	`~/.busabase/.env`
Space	`--space-id <id>`	`BUSABASE_SPACE_ID`	`~/.busabase/.env`

See Troubleshooting if backup/restore can't reach a host or comes back 401/403 — the same host/auth rules that apply to the rest of busabase-cli apply here.

Not supported

--state-only is recognized but will not be implemented — it is superseded by export / install, which cover the same "content without history" need in a format you can actually read and diff. Running backup --state-only prints that guidance and exits.

These are recognized but not implemented yet — they fail fast with a clear error rather than doing something unexpected:

--resume (continue a restore that was interrupted partway through)
--into-folder (only applies to state-only archives — use install --into-folder instead)

See also: Install & Export · Bring Your Own Agent · API Tokens · REST API · Troubleshooting

Backup & Restore

On this page