CLI

Installation

# Use via npx (recommended)
npx @buildpad/cli@latest --help
 
# Or install globally
npm install -g @buildpad/cli

Commands

Adding Components

# Add single component
buildpad add input
 
# Add multiple components
buildpad add input select-dropdown datetime
 
# Add collection-form (includes VForm + all dependent interface components)
buildpad add collection-form
 
# Add all components from a category
buildpad add --category selection
 
# Add all components (non-interactive)
buildpad add --all
 
# Interactive selection
buildpad add

Import Transformation

When components are copied to your project, all internal imports are automatically transformed:

import { useRelationM2M } from '@buildpad/hooks';
import type { M2MItem } from '@buildpad/types';

import { useRelationM2M } from '@/lib/buildpad/hooks';
import type { M2MItem } from '@/lib/buildpad/types';

Every import form is rewritten: static and type-only imports, export … from, side-effect imports, import(), require() and declare module. If a file imports a @buildpad/* path that the CLI cannot place in your project, add and upgrade stop with an error that names the file, the line and the import. They do not copy an import that would fail in your build. buildpad validate reports any @buildpad/* import left in the folders the CLI installs into, and buildpad fix rewrites them. Both leave imports of the published @buildpad/cli and @buildpad/mcp packages alone.

Versioning & Upgrades

Buildpad tracks per-file SHA-256 checksums in buildpad.json so it knows exactly what was installed and whether you’ve modified it locally.

# See which installed components have newer versions
buildpad outdated
 
# Upgrade all components
buildpad upgrade --all
 
# Upgrade specific components
buildpad upgrade input vform
 
# Preview what would change without writing files
buildpad upgrade --all --dry-run

upgrade brings dependencies along. The new code of an entry imports the new code of what it depends on, so the out-of-date components and lib modules an upgraded entry depends on are upgraded in the same run, and the ones your project does not have are installed. The run lists them first, with the entry that needs each one. Entries that nothing you selected depends on are left alone. Pass --no-deps to upgrade only the entries you name; the project may then not compile until their dependencies are upgraded too.

When a component has been locally modified, upgrade will prompt you for each file. You can control the behaviour with --strategy:

# 3-way merge for conflict resolution
buildpad upgrade --all --three-way
 
# Write .new files for all modified files (keep originals)
buildpad upgrade --all --strategy=new-file

Re-syncing with --force

Without a terminal (CI, a pipe, the MCP server) upgrade asks nothing. A locally-modified file keeps your version and the new one is written as <file>.new, as with --strategy=new-file; pass --strategy to choose. Missing npm packages are listed with the command that installs them, but are not installed; pass --yes to install them (it also overwrites modified files).

upgrade skips any component whose installed version already matches the registry. Pass --force to re-sync anyway — it bypasses the version check but still honours --strategy, so locally-modified files are merged, not clobbered:

# Re-sync every installed component to current source
buildpad upgrade --force --three-way
 
# Re-sync specific components
buildpad upgrade input vform --force

With --force and no component arguments, the default target is all installed components (not just outdated ones).

Upgrading the design system

The design foundation — app/design-tokens.css, app/globals.css, lib/theme.ts, and the app shell (ColorSchemeToggle, AuthenticatedShell) — is installed by init/bootstrap as the design-system lib module and tracked in buildpad.json. Unlike before, it’s now upgradeable:

# Refresh the design system to the latest registry version
buildpad upgrade --design
 
# Merge your local token edits instead of overwriting
buildpad upgrade --design --three-way

Because token/theme files are meant to be customized, --design honours the same --strategy rules as components: pristine files are overwritten cleanly, locally-modified files are three-way merged (or written as .new) — your edits are never silently lost. A bare buildpad upgrade also picks up the design system when it’s behind, and buildpad outdated reports it. Projects that have the design files but predate this tracking are adopted on the first upgrade --design.

Note: bootstrap wires AuthenticatedShell into the generated app/[lang]/(authenticated)/layout.tsx by default, but upgrade only refreshes the design-system files — your layout wiring (and any nav/brand customization) is your application code and is never rewritten. See App Shell.

Changelogs

# See what changed between your installed version and latest
buildpad changelog input
buildpad changelog @buildpad/ui-interfaces
 
# Filter from a specific version
buildpad changelog @buildpad/ui-form --since=1.3.0

Migration from v1

If your buildpad.json was created before v2, run migrate once to compute SHA-256 checksums and enable safe upgrades:

# Preview migration
buildpad migrate --dry-run
 
# Apply migration
buildpad migrate

migrate baselines every component to the current registry version — it cannot reconstruct the version a component was originally installed at, because v1 buildpad.json never recorded per-package versions. So immediately after migrating, outdated and upgrade will report everything up to date even if your installed files lag behind current source.

To actually re-sync a freshly-migrated project, follow up with a forced upgrade:

# Re-sync all components to current source (merges local edits)
buildpad upgrade --force --three-way
 
# Confirm the result
buildpad status

Note: three-way merge fetches its merge base from a git tag for the installed version. A pre-v2 project usually has no such tag, so locally-modified files fall back to .new files for manual resolution — pristine files still re-sync cleanly. From your next release onward, outdated and upgrade work normally with no --force needed.

Validation

The validate command checks for common issues:

• Untransformed imports — @buildpad/* imports that weren’t converted
• Missing lib files — Required utility modules not installed
• Missing CSS files — CSS required by rich text/block editors
• SSR issues — Components exported without SSR-safe wrappers
• Missing API routes — DaaS integration routes not created

# Validate your installation
buildpad validate
 
# Auto-fix found issues
buildpad fix