Workspaces

A Buildprint workspace is a local copy of one Bubble app branch. You clone a branch into a workspace, edit files inside it, validate the result, and apply your changes back to Bubble. Everything the CLI does on behalf of one branch happens inside that branch's workspace.

One workspace = one Bubble branch. If you want to work on two branches of the same app in parallel, you clone each one into its own workspace under a shared app root.

Anatomy

A workspace is made of two folders:

The app root — one directory per Bubble app. It holds internal Buildprint state (the local git history of the app) and is shared by every branch workspace you create for that app.
The branch folder — a sibling directory inside the app root, one per Bubble branch. This is the folder you actually edit in. It is a git worktree: a normal git checkout backed by the shared app-root history.

my-app/                   # app root
  .buildprint/            # internal state, do not edit
  test/                   # branch workspace for Bubble branch "test"
    app.json
    pages/
    data_types/
    ...
  live/                   # branch workspace for Bubble branch "live"
    ...

Inside a branch folder you get normal files and folders: pages, reusable elements, mobile views, data types, option sets, styles, API connector calls, workflows, and actions. See File system for the full layout.

Lifecycle

The lifecycle of one workspace has four stages. Steady-state editing is the loop in the middle - the two endpoints (clone and destroying the folder) only happen once.

Clone the branch into a fresh workspace.
Explore and edit locally. Read files with ordinary tools; use summary, tree, and context when you need to navigate the app. Make changes with your editor or with new/copy.
Check and apply your committed changes back to Bubble.
Sync when Bubble changes (there's no need to do this after apply, but if the user indicates they've made changes to the Bubble branch in the editor, we'll need to sync as those changes only exist on the remote).

1. Clone the branch

buildprint project clone <appId> --branch <name>

By default this creates <appId>/<branch>/ in the current directory. Use --dir <path> to put the app root somewhere else. The default branch is test.

What clone does:

If the app root does not exist yet, it is created and the full Bubble snapshot is fetched into the local git history.
If the app root already exists for the same app, clone reuses the local history and just adds a new branch worktree. If the branch is new to this app root, the snapshot is fetched for that branch.
The branch folder must be empty or missing. Clone refuses to overwrite an existing folder — if there's already content there, the correct move is to cd into it and run buildprint sync instead.

After a fresh clone the CLI prints the exact folder path to cd into. From that moment on, run every command from inside that folder.

2. Explore and edit

From inside the branch folder you can:

Read files with your editor, cat, or any git tool. Use git diff to review changes as you work.
Navigate with buildprint summary (top-level surfaces), buildprint tree <target> (element and workflow subtrees), and buildprint context <target> (relationships for one node).
Create new entities with buildprint new (pages, data types, workflows, actions, and more) and duplicate existing ones with buildprint copy. These commands produce canonical JSON and update the workspace cache in place.
Edit anything else directly in the files. The CLI does not hide any part of the editable surface.

Commit often. Small commits make the apply step easier to reason about and leave a clean history if you later need to roll back.

3. Check and apply

Before sending changes back to Bubble, run buildprint check to catch syntax issues.

buildprint check
buildprint apply

Apply runs an internal check gate first, auto-commits any uncommitted changes, diffs against the Bubble snapshot, and sends a minimal set of updates to Bubble. On success, the Bubble snapshot ref advances to match what Bubble now contains.

See Validating with check and Applying changes for flag-level detail.

4. Sync when Bubble changes

buildprint sync

Sync fetches the latest Bubble snapshot for the current branch and merges it into your workspace. If nothing has changed, sync is a no-op; if Bubble moved ahead cleanly, it is a fast-forward; otherwise you get ordinary git conflict markers to resolve.

Run sync in two situations:

Before starting a new piece of work, so you begin from Bubble's current state.
Whenever you suspect Bubble has changed under you (someone edited in the browser, or you restored a savepoint).

Multiple workspaces for the same app

You can keep several branches of the same app open at once. Just clone each one into the same app root:

buildprint project clone my-app --branch test
buildprint project clone my-app --branch live

The two workspaces end up as sibling folders under my-app/. Switch between them with cd. Each folder has its own git branch checked out and its own pending changes.

The branch folder name and the checked-out git branch must match. If you rename the folder or change branches, the CLI stops and prints the exact cd or git checkout you need. This guard stops you from accidentally applying to the wrong branch.

Safety rails

A few invariants protect you from obvious mistakes:

Branch folder = git branch - enforced on every mutating command.
Apply is gated by check - any error-level issue blocks the apply unless you pass --no-check (don't do this!).
Suspicious shrinks are blocked - sync refuses to replace a large workspace with a tiny fetched snapshot unless you explicitly allow it with --allow-suspicious-shrink. Same logic for apply --allow-large-apply in the opposite direction.
No overwriting a non-empty clone target - clone asks you to sync instead if the folder already has content.

Cleaning up

A workspace is just a folder. To remove one branch's workspace:

Make sure you have applied or abandoned any pending changes.
From outside the branch folder, delete it with rm -rf <app-root>/<branch>.

To drop the entire local copy of an app, remove the whole app root. This only affects your local workspace — nothing is sent to Bubble, and you can buildprint project clone again at any time.

Where commands should run

Almost every CLI command expects to be run from inside the branch folder. These are the exceptions:

buildprint link, buildprint project list, buildprint project info, buildprint project clone - do not require a workspace.
buildprint docs and buildprint guidelines - documentation lookups, can be run anywhere.
buildprint branch list and buildprint branch create - work from anywhere, but the single-argument form of branch create only resolves an app id when you run it inside an app root.

Everything else (sync, check, apply, tree, summary, context, new, copy, savepoint, schema) requires a branch workspace.

Was this helpful?