Run a blueprint from the command line

The command line interface (CLI) is a program you run by typing a command in a terminal. A terminal is the window where you type commands: Terminal on a Mac, PowerShell on Windows. The BuildBase CLI is part of the @buildbase/sdk package, and it runs the same validate, plan and apply as the console.

npx buildbase blueprint validate   # check the file, change nothing
npx buildbase blueprint plan       # list what would change
npx buildbase blueprint apply      # make the changes, after you type yes

The blueprint commands ship in @buildbase/sdk 1.0.0. If a command answers Unknown command: blueprint, you ran an earlier version.

Install nothing beyond Node

Node.js comes with npx, which downloads a package and runs it. You do not need to install anything else.

• In a project that already has the SDK installed, run npx buildbase blueprint .... It uses the SDK in that project.
• Anywhere else, run npx @buildbase/sdk blueprint .... The first time, npx asks to download the package: type y and press Enter.

The examples on this page use npx buildbase. Replace it with npx @buildbase/sdk when the SDK is not installed in your project.

Set the two variables safely

The CLI reads two environment variables: named values that your terminal passes to every program it starts. They stay in that terminal window only, and are gone when you close it.

The CLI never takes the API key as an option, so it does not end up in your shell history or in a log. Type it with a command that hides what you type.

On a Mac or Linux:

export BUILDBASE_SERVER_URL=https://api.console.buildbase.app
read -rs BUILDBASE_API_TOKEN && export BUILDBASE_API_TOKEN

On Windows, in PowerShell 7.1 or later:

$env:BUILDBASE_SERVER_URL = "https://api.console.buildbase.app"
$env:BUILDBASE_API_TOKEN = Read-Host -MaskInput "API key"

After read -rs or Read-Host, paste the key and press Enter. Nothing shows while you paste, on purpose.

--server-url sets the server for one command instead of BUILDBASE_SERVER_URL. If neither is set, the CLI also reads NEXT_PUBLIC_BUILDBASE_SERVER_URL, the variable a Next.js app with the SDK already has.

Values for ${env:NAME}

A blueprint writes each secret as ${env:NAME} (see secrets). The CLI fills each one from an environment variable of that name, or from a file named with --env-file:

APP_URL=https://staging.acme.example
STRIPE_SECRET_KEY=sk_test_your_key_here

npx buildbase blueprint plan --env-file .env.staging

• A variable already set in the terminal wins over the same name in the file.
• Only the names the blueprint uses are sent to BuildBase. The rest of your environment stays on your computer.
• --env-file does not supply BUILDBASE_API_TOKEN. Set that one in the terminal.
• Keep files such as .env.staging out of Git: add them to .gitignore.
• Check the file name. On Node.js 20 and 22, Node reads --env-file too, so a file that does not exist stops Node itself with node: .env.staging: not found before the CLI starts.

Commands

validate, plan and apply read buildbase.blueprint.json in the folder you run them from. To use another file, name it after the command: npx buildbase blueprint plan staging.blueprint.json.

validate

npx buildbase blueprint validate

It lists each problem with the place in the file, then the ${env:NAME} values that are not set yet, after Not set (needed to apply):. A valid file ends with buildbase: buildbase.blueprint.json is valid., and a file with problems ends with is not valid.

plan

npx buildbase blueprint plan --env-file .env.staging

It prints one line for each thing that would change, then a summary. Add --verbose to also list what is unchanged. How to read a plan explains every symbol.

apply

npx buildbase blueprint apply --env-file .env.staging

1. The CLI makes a plan and prints it.
2. It asks Apply these changes to the organization? Type "yes" to go ahead:. Type yes and press Enter. Any other answer stops it, and nothing changes.
3. It applies the plan you saw, by sending that plan's hash. If your organization changed since that plan, BuildBase refuses, and you plan again.
4. It prints each step and a recheck: the plan made again, which shows anything still different.

When there is nothing to change, it says the organization already matches the file, and stops. If a step fails, it says which one, and that the steps before it were applied.

export

npx buildbase blueprint export --out buildbase.blueprint.json

Without --out, it prints the blueprint in the terminal. With --out, it writes the file. Either way, it lists the secrets to set before you plan the file. It does not replace a file that exists unless you add --force.

schema

npx buildbase blueprint schema --out blueprint.schema.json

Options

An option that takes a value works as --out file or --out=file.

Exit codes

When a command ends, it returns a number, its exit code. Scripts and CI read it to decide what to do next.

A version of the SDK from before the blueprint commands answers Unknown command with exit code 2. So a script that reads 2 as "changes found" should run validate first: an SDK without the commands fails there.

Where shown-once values go

An apply that creates a webhook, an API key, an auth client, a text message webhook or web push keys gets values that BuildBase shows only once. The CLI never prints them, even with --json: the result says (shown only once, so it is not printed here) for each one. It adds them to .buildbase/blueprint-outputs.json (or the --outputs file), under the address of the thing that made them, and prints the file name.

• On a Mac or Linux, the file is created so that only your user account can read it.
• Before it changes anything, apply checks the file. If a file with that name exists and is not an outputs file, apply stops, so it never writes over another file.
• Move the values to your password manager or secret store, then delete the file.
• Add .buildbase/ to your .gitignore, so the file is never committed.

Check for drift in CI

Drift means the organization no longer matches the file, because someone changed a setting in the console. CI (continuous integration) is a service that runs commands for you, on a schedule or when code changes. This GitHub Actions workflow plans every weekday morning and fails when the organization has drifted from the file in your repository:

name: Blueprint drift
on:
  schedule:
    - cron: '0 7 * * 1-5'
  workflow_dispatch:

jobs:
  plan:
    runs-on: ubuntu-latest
    env:
      BUILDBASE_SERVER_URL: https://api.console.buildbase.app
      BUILDBASE_API_TOKEN: ${{ secrets.BUILDBASE_API_TOKEN }}
      APP_URL: ${{ vars.APP_URL }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Validate the file
        run: npx --yes @buildbase/sdk blueprint validate
      - name: Plan
        run: |
          code=0
          npx --yes @buildbase/sdk blueprint plan || code=$?
          if [ "$code" = 2 ]; then
            echo "::error::The organization no longer matches buildbase.blueprint.json"
          fi
          exit $code

1. In your repository on GitHub, open Settings, then Secrets and variables, then Actions.
2. Add a secret named BUILDBASE_API_TOKEN with your API key.
3. Add a variable for each ${env:NAME} the file uses outside a secret field, such as APP_URL. Secrets in the file are optional for a drift check: a secret that is not set is not compared.
4. Commit the workflow file next to buildbase.blueprint.json.

--yes after npx lets it download the package without asking. To apply from CI, for example after a change is merged, run npx --yes @buildbase/sdk blueprint apply --yes, and store the shown-once values it writes before the job ends.

Next steps

• File format - what each section of the file holds
• AI agents - run these commands from an AI coding agent
• Troubleshooting - what each message means and what to do