All Collections

Creating and copying entities

The new and copy commands create or duplicate Bubble entities with correct shape and fresh ids. They update the workspace in place so that a follow-up buildprint apply sends the changes back to Bubble.

Both commands must be run from inside a branch workspace. The branch folder name must match the checked-out git branch - if not, the CLI will print the exact git checkout or cd to run.

Creating entities: new

Pages, reusables, mobile views

buildprint new page --name "Checkout"
buildprint new reusable --name "Header" --element-type Group
buildprint new mobile_reusable --name "Nav" --element-type Group
buildprint new mobile --name "Home"

Use --copy <id-or-name> on any of these to clone an existing root with fresh ids.

Data types

buildprint new data_type --name Order --field status:text --field owner:user --field total:number

Each --field is display:value (for example owner:user). Repeat the flag for each field. Pass --exposed-api to expose the type on the Data API.

New data types ship with a default privacy rule: everyone can see the record, and only the creator is visible by default. Tighten it from the workspace file before applying.

Option sets

buildprint new option_set --name OrderStatus --value Pending --value Paid --value Cancelled

Values accept either a bare display (Paid, db value auto-derived) or an explicit Display:db_value pair. Repeat --value for each option. Use --attribute display:value to define attributes on the set.

Workflows

buildprint new workflow --path api --name "Create Order" --type APIEvent --param items:text[] --returnParam id:text
buildprint new workflow --path pages/home/workflows --name "Click Buy" --type ButtonClicked

Important flags:

  • --path — owner root. api for API workflows, pages/<page-id>/workflows, element-definitions/<id>/workflows, and so on. Subfolders are allowed (pages/home/workflows/modals).

  • --type — one of the Bubble workflow types (APIEvent, CustomEvent, ButtonClicked, PageLoaded, ConditionTrue, etc).

  • --param <spec> — repeat for each input parameter. Spec syntax: name:type, with optional [] for list and ? for nullable. Example: users:user[]?. Quote the value in zsh.

  • --returnParam <spec> — only valid for APIEvent (backend workflow) and CustomEvent (custom event). Adds a terminating return action automatically, as well as the return data properties for custom events.

  • --folder <name> — place the workflow in a named subfolder under the owner path.

  • --actions <count> — prefill the workflow with N empty actions.

Actions

buildprint new action --path api/create-order --type CreateThing
buildprint new action --path api/create-order --type SetState --after 2

  • --path — path to the workflow file.

  • --after <step-or-id> and --before <step-or-id> - mutually exclusive. Accepts a zero-based step index or an action id.

  • --name <override> — give the action an explicit display name.

Inserting into the middle of a workflow is refused if any later action references its predecessors, because shifting the steps would silently break those references. The error lists the blocking actions; resolve them (or append at the end) and retry.

Folders

buildprint new folder --path api --name "Billing"

Creates a workflow folder under the given owner path. Fails if the folder already exists.

Copying entities: copy

Copy a root

buildprint copy root --kind page --source "Checkout" --name "Checkout Copy"

--kind is one of page, mobile, reusable, mobile_reusable. --source accepts a display name or id.

Copy a workflow

buildprint copy workflow --source api/create-order --path api --folder "Billing" --name "create-order-v2"

Duplicates a workflow into a different owner or folder, rewriting ids and stripping alias metadata.

Copy an element subtree

buildprint copy element --source pages/home/elements/grp_header --path pages/checkout

Copies the element and its descendants under the destination parent.

Copy actions

buildprint copy action --from api/create-order --path api/refund-order --source 0 --source 1 --after 2

  • --source — repeat for each step you want to copy. Accepts a step index or an action id.

  • --name — only allowed when copying exactly one action.

  • --after and --before — mutually exclusive insertion points. Omit to append.

Copy refuses to move actions whose PreviousStep references point outside the copied set — the resulting workflow would be broken. The error message tells you which action is blocking and why.

Generating ids by hand

If you ever need fresh Buildprint ids for a manual edit, use buildprint utils generate-ids <n>. n must be between 1 and 100. Keep them short-ish.

You can also create any entities manually. buildprint new is simply a shortcut to make it easier for most cases.

Was this helpful?