Getting started

The Buildprint CLI lets AI agents inspect and change Bubble apps from a coding environment.

How agents use the CLI

The CLI connects an agent to a Bubble app and provides the tools needed to work with it.

An agent can:

• find the Bubble app and branch it should use;

• clone the branch into a local workspace;

• read and edit the app as BubbleScript;

• check changes before writing them; and

• apply the checked changes to Bubble.

The CLI is installed in every Buildprint Agent runtime. It can also be installed in another agent environment.

Access and permissions

The CLI can only access the projects and actions allowed by its authentication.

Buildprint Agent runtimes receive scoped access automatically. Their access follows the projects, branches and Plan or Build permissions selected for the conversation.

For another agent environment, install the CLI and link it with a token created from Integrations → Access tokens:

npm install -g buildprint
buildprint link <token>

Choose an app and branch

The agent identifies the exact Bubble project and branch before cloning it.

For example, it can list the available projects and branches for our example app:

buildprint project list
buildprint branch list acme-app

Bubble normally uses test as its main development branch. An agent can also work on an existing feature branch when it has access.

Clone the Bubble app

Cloning creates a local BubbleScript workspace for one Bubble branch.

buildprint project clone acme-app --branch test

The agent can search and read the workspace like a codebase. Cloning is read-only and does not change the Bubble app.

Change the app

The agent edits the BubbleScript files in the cloned workspace.

It can change supported parts of the app such as pages, reusable elements, responsive behaviour, workflows, data types and option sets. Local edits do not affect Bubble until they are applied.

Check the change

buildprint check validates the BubbleScript and shows the Bubble changes it will produce.

buildprint check

The check reports invalid syntax, missing references, incorrect values and unsupported changes. Checking does not write anything to Bubble.

Apply the change

buildprint apply compiles the checked BubbleScript into Bubble JSON and sends the changes to the selected branch.

buildprint apply

The apply stops if the local source or Bubble branch has changed since the check. After a successful apply, the changes are visible in the Bubble editor.

Sync editor changes

buildprint sync updates the local workspace when someone changes the same branch in Bubble.

buildprint sync

The latest Bubble state is converted back into BubbleScript and merged with the agent’s local work. The agent resolves any conflicts and checks the result again before applying.

Use runtime tools

The CLI also gives agents tools for the running Bubble app.

• buildprint data reads or changes database records.

• buildprint logs investigates runtime events.

• buildprint login signs a browser into run mode.

• buildprint screenshot captures the running app.

• buildprint file works with Bubble’s file manager.

These actions are separate from BubbleScript source changes.