All Collections

Workspaces

A Buildprint workspace is a local editable copy of one Bubble app branch. You clone a branch, edit the shredded files, validate the result, and apply the changes back to Bubble.

One workspace maps to one Bubble branch. If you want to work on two branches of the same app, keep them as sibling branch folders under the same app root.

Anatomy

A cloned app has an app root and one or more branch workspaces:

my-app/
  .buildprint/
    app.json
    remote.git/
  test/
    .git
    .gitignore
    app.json
    settings/
    data_types/
    option_sets/
    styles/
    pages/
    element-definitions/
    mobile-views/
    global-elements/
    api/
    tests/
    issues/
  staging/
    ...

The app root stores shared Buildprint state for the Bubble app. Each branch folder is a real git worktree. The folder name must match the checked-out git branch; mutating commands stop with guidance if they do not match.

Do not edit .buildprint/ by hand. The files you edit live inside the branch folder.

Clone a branch

buildprint project clone <appId>
buildprint project clone <appId> --branch staging
buildprint project clone <appId> --branch live --dir ./my-app

The default branch is test. --dir sets the app root; the branch workspace is still created at <app-root>/<branch>/.

Clone creates a new app root if needed. If the app root already exists for the same app, clone reuses the shared history and adds another branch worktree. The target branch folder must be empty or absent; clone will not overwrite existing content.

Use these before cloning when you need to inspect access:

buildprint project list
buildprint project info <appId>
buildprint branch list <appId>

The normal loop

Most work follows this loop from inside the branch folder:

buildprint sync
git status
# edit files, or use buildprint new / buildprint copy
buildprint check
buildprint apply

sync fetches the latest Bubble snapshot, updates the local Bubble snapshot ref, and merges it into the current branch. It also syncs the app-global tests/ snapshot. Use buildprint sync --no-merge when you want to fetch the snapshot but merge it yourself later.

check validates the pending changes against the current Bubble snapshot. Run the unfiltered buildprint check before apply; targeted path checks are useful while editing but do not satisfy apply freshness.

apply requires a fresh successful unfiltered check for the current pending changes unless you pass --force-apply. It auto-commits unapplied workspace edits when needed, compiles the diff into Bubble writes, sends changed tests/ definitions, and advances local refs on success.

When to sync

Run buildprint sync:

  • Before starting new work on an existing branch.

  • After someone edits the same Bubble branch in the Bubble editor.

  • After restoring a Bubble savepoint.

  • Before auditing or reviewing a branch whose remote state may have moved.

A clean sync can fast-forward or create a normal merge commit. If both Bubble and the local branch changed the same files, sync leaves ordinary git conflict markers for you to resolve.

Multiple branch workspaces

Clone additional branches into the same app root:

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

Switch branches by changing directories, not by checking out a different git branch inside a branch folder that belongs to another Bubble branch:

cd my-app/test
cd ../staging

Commands that can run outside a workspace

These commands do not require a branch workspace:

  • buildprint link <token>

  • buildprint project list

  • buildprint project info <appId>

  • buildprint project clone <appId>

  • buildprint branch list <appId>

  • buildprint docs ...

  • buildprint guidelines ...

  • buildprint update

  • buildprint mcp install ...

Some commands accept explicit app and branch flags outside a workspace, such as buildprint login --app <appId> --branch <branch> and buildprint data ... --app <appId> --version <branch>.

Everything that reads or mutates local app files, including sync, check, apply, summary, tree, context, new, copy, savepoint, audit, and most test-user commands, expects to run from inside a branch workspace.

Safety rails

Buildprint protects the common failure modes:

  • Branch folder and git branch must match for mutating workspace commands.

  • apply requires a fresh successful unfiltered buildprint check for the current pending changes.

  • apply --no-check skips the internal rerun, but still requires the fresh check record.

  • apply --force-apply bypasses the check freshness and validation gates. Use it only for exceptional recovery.

  • Suspicious snapshot shrink or growth is blocked unless you explicitly allow it with sync --allow-suspicious-shrink or apply --allow-large-apply.

  • Clone refuses to overwrite a non-empty branch folder.

Cleaning up

A branch workspace is local only. To remove it, make sure pending work is applied or intentionally abandoned, then delete the branch folder from outside it:

rm -rf my-app/staging

To remove the whole local copy of an app, delete the app root. Nothing is sent to Bubble by deleting local folders.

Was this helpful?