Creating and copying entities

Use buildprint new and buildprint copy to create valid Bubble entities with fresh ids and canonical JSON. These commands run inside a branch workspace and update the local files in place.

After creating or copying entities, inspect the diff, run buildprint check, then buildprint apply.

Canvas roots

Create pages, reusable elements, mobile views, and mobile reusables:

buildprint new page --name "Checkout"
buildprint new page --name "Dashboard" --layout column
buildprint new reusable --name "Header" --element-type Group
buildprint new reusable --name "Create Modal" --element-type Popup
buildprint new mobile --name "Home"
buildprint new mobile_reusable --name "Account Sheet" --element-type Sheet

--layout accepts column, row, or fixed. Use --copy <id-or-name> to clone an existing root with fresh ids:

buildprint new page --name "Dashboard Copy" --copy "Dashboard"
buildprint new reusable --name "Sidebar Copy" --copy "Sidebar"

Data types

buildprint new data_type --name "Project"
buildprint new data_type --name "Invoice" --field total:number --field owner:user
buildprint new data_type --name "Project API" --exposed-api --field status:option.project_status

Each --field uses display:value, for example owner:user. New data types include default privacy-role scaffolding. Review privacy rules before applying.

Option sets

buildprint new option_set --name "Project Status"
buildprint new option_set --name "Project Status" --value Open --value Closed
buildprint new option_set --name "Project Status" --value "In Progress:in_progress"
buildprint new option_set --name "Evidence Strength" --value High --value Moderate --attribute color:text --attribute threshold:number

Values can be bare display labels or Display:db_value. Attributes use display:value.

Workflows

buildprint new workflow --path api --name "Use Tool" --type CustomEvent
buildprint new workflow --path api --folder "Tools" --name "Use Tool" --type CustomEvent --param toolCallName:text --param toolCallArguments:text --actions 2
buildprint new workflow --path api --name "Find User" --type CustomEvent --param email:text --returnParam user:user --actions 1
buildprint new workflow --path api --name "Lookup User" --type APIEvent --param email:text --returnParam user:user
buildprint new workflow --path pages/home/workflows --name "Page Loaded" --type PageLoaded
buildprint new workflow --path pages/home/workflows/modals --name "Open Modal" --type ConditionTrue

Important flags:

--path <path> points to the workflow owner, such as api, pages/home/workflows, or an existing workflow folder.
--folder <folder> creates or uses a workflow folder under the owner.
--type <type> is the Bubble workflow event type, such as APIEvent, CustomEvent, PageLoaded, or ConditionTrue.
--param <name:type> adds workflow inputs. Use [] for lists and ? for optional values, for example users:user[]?.
--returnParam <name:type> is supported for APIEvent and CustomEvent.
--actions <count> creates placeholder action files.

Actions

buildprint new action --path api/tools/use-tool --type TriggerCustomEvent
buildprint new action --path api/tools/use-tool --type ScheduleAPIEvent --name "Schedule audit event"
buildprint new action --path pages/home/workflows/load-page --after 0 --type HideElement
buildprint new action --path pages/home/workflows/modals/open-popup/workflow.json --before bpAction123 --type ShowElement

--after and --before accept a zero-based step key or action id and cannot be used together. Inserting in the middle of a workflow is refused when later actions contain positional previous-step references that would become unsafe.

Workflow folders

buildprint new folder --path api --name "Tools"
buildprint new folder --path pages/home/workflows --name "Modals"

The path must be a workflow owner root, not an existing folder path.

Project tests

Create local Buildprint project tests and reusable test components under tests/:

buildprint new test --name "Checkout"
buildprint new test --name "Checkout" --folder smoke
buildprint new test --component --name "Login"
buildprint new test-step --path tests/smoke/checkout.json --type test --instruction "Open checkout"
buildprint new test-step --path tests/smoke/checkout.json --type component --component login

test-step supports step types test, condition, and component. Useful options include --parent, --condition met|not_met, --details, --tips, and --on-failure stop|continue.

Copying roots

buildprint copy root --kind page --source "Marketing Home" --name "Marketing Home Copy"
buildprint copy root --kind reusable --source "Sidebar" --name "Sidebar Copy"

--kind accepts page, mobile, reusable, and mobile_reusable. --source accepts an id, raw key, or display name.

Copying workflows, elements, and actions

buildprint copy workflow --source api/tools/use-tool --path api --folder "Backups" --name "Use Tool Copy"
buildprint copy element --source pages/home/elements/sidebar --path pages/home
buildprint copy action --from api/tools/use-tool --source 0 --source 1 --path pages/home/workflows/load-page --after 1

Copy rewrites ids, strips alias metadata, and preserves safe references. Copying actions refuses unsafe previous-step references that point outside the copied set.

Generating ids manually

For manual edits, mint fresh Buildprint ids with:

buildprint utils generate-ids
buildprint utils generate-ids 20

N must be between 1 and 1000. Prefer new or copy when possible because they also create the correct surrounding file shape.

Was this helpful?