Skip to content
BuildBase

The buildbase CLI

Every buildbase command - init, login, env, blueprint, import, content pull and the agent tools - with its options and which SDK release has it.

buildbase is a command-line tool (CLI) for setting up BuildBase from your terminal. It wires the SDK into your app, signs your computer in to the console, points your app at a test environment, and more. It ships inside @buildbase/sdk, so you run it with npx in your app's folder and there is nothing to install globally.

npx buildbase init                       # wire the SDK into this app
npx buildbase login                      # sign this machine in to your console
npx buildbase init --dev                 # point the app at your development environment
npx buildbase agent doctor --url https://app.example.com/api/mcp

npx buildbase --help lists the commands, and npx buildbase <command> --help the options of one. It never takes an API token or a client secret as an argument, where it would end up in your shell history. Those come from an environment variable, or a file only you can read. For import, Firebase's signer key can be a flag, but BUILDBASE_FIREBASE_SIGNER_KEY keeps it out of your history.

Which release has which command

CommandWhat it doesIn @buildbase/sdk
initWire the SDK into the app in this folder0.0.79 and later
content pullFetch published content to a JSON file0.0.73 and later
importImport users from Clerk, Auth0, Firebase or Supabase0.0.90 and later
login, logoutSign this machine in to your console with a device code1.0.0 and later
init --dev, envPoint the app at a development or staging environment, and promote changes1.0.0 and later
blueprintSet up a whole organization from one JSON file, and serve it to coding agents1.0.0 and later
agent doctor, install, listingCheck your MCP server, print install links for every client, write listing files1.0.0 and later

Each command needs the @buildbase/sdk version in its row, or a later one. On 0.0.90, npx buildbase --help lists init, content pull and import only.

init

init sets up the SDK in a Next.js (App Router), Vite or Express app. It writes the provider (the component that connects your app to BuildBase), the three auth routes, a webhook route, .env.example and .env.local, and wraps your root layout. It never overwrites a file and leaves secrets empty. Running it twice prints already configured. The full walk-through is in Installation.

OptionWhat it does
--framework <name>nextjs, vite or express; detected from package.json when left out
--org-id <24 hex>Your organization id from the console
--server-url <url>The API server; the cloud one by default
--client-id <id>The sign-in client's id
--redirect-url <url>Where sign-in returns to; the app's local address by default
--no-installSkip npm install of the SDK
--yesTake every prompt's default (an empty folder becomes a Next.js app)
--devWire the app to your development environment, client secret included. Needs login first
--env <name>With --dev: the environment to wire, by name or key (Development by default)
--rotate-secretWith --dev: mint a new client secret even if one was handed out before

login and logout

buildbase login signs your computer in to your BuildBase console, the way you sign in to an app on a TV. It prints a short code and the address of the console's /device page. You approve the sign-in there, in a browser where you are already signed in to the console.

The console token is then saved to credentials.json in your config folder, readable only by you. It is never printed and never passed as a flag. Commands that act on your console (init --dev, env) use it.

OptionWhat it does
--openOpen the approval page in your browser
--jsonPrint the outcome as one JSON document, without the token
--central-url <url>Another console's central server (or BUILDBASE_CENTRAL_URL)

BUILDBASE_CONFIG_DIR moves the token file. Exit codes: 0 signed in, 1 an error, 2 a usage error, 3 the sign-in was denied, 4 the code expired before it was approved.

buildbase logout removes the stored token. The session stays listed on your console's Security page until it expires or you end it there.

Environments

After login, these commands point the app at one of your development or staging environments, and move configuration between it and production.

The ones that write .env.local fill in the server URL, org id, environment key (the eight lowercase letters that name the environment), sign-in client and client secret. They make the file readable by its owner only, and write it only when git ignores it, so the secret is never committed.

CommandWhat it does
init --devWire the app to Development (or --env <name>) with no console step
env listYour organization's environments, with their keys
env use <name>Point .env.local at one; with --rotate-secret, a new client secret
env create <name>Add an environment (owner or admin, within your plan) and point .env.local at it, client secret included
env diff <name>What pushing its unsubscribe groups, email templates, workflows, plans and plan groups to production would change, item by item
env push <name>Promote them to production: a workflow lands as a draft, a plan as a new draft version with no Stripe ids, a template or group changes in place
env pull <name>Bring production's configuration into the environment, the same way

push and pull show the diff and ask before they change anything. --yes answers for them in a run with no terminal, and --only <kind:key> narrows the run to one item. --org-id names the organization when your login belongs to several; you must be a member of it.

The client secret is handed out once per environment. A second use or --dev says so. --rotate-secret mints another, and the one before stops working.

blueprint

A blueprint is one JSON file, buildbase.blueprint.json, that describes how your organization is set up: sign-in, email, billing, roles, webhooks and the rest. buildbase blueprint checks it, shows what would change, and applies it. Blueprints covers it step by step.

SubcommandWhat it does
validate [file]Check the file: format, links between entries, secrets. Changes nothing
plan [file]Compare the file with the organization and list what would change
apply [file]Show the plan, ask you to type yes, make the changes, then check again
exportWrite the organization's current setup as a blueprint, secrets as ${env:NAME} placeholders
schemaWrite the JSON Schema, for editors and AI agents
mcpServe these as tools to a coding agent over stdio (AI agents)

It needs BUILDBASE_API_TOKEN (an owner or admin API key) and BUILDBASE_SERVER_URL. Some values are shown only once by an apply, such as webhook signing secrets and API keys. Those go to .buildbase/blueprint-outputs.json, readable only by you, never to the terminal.

Exit codes: 0 nothing to change or applied, 2 the plan has changes, 1 an error. So a CI job (an automated check that runs on every push) can tell "the organization no longer matches the file" from "something broke".

import

buildbase import --from <clerk|auth0|firebase|supabase> <file> moves your users over from another sign-in provider's export file. It carries each user's email, verified status, name, old id and phone, and their Google, GitHub, Microsoft, Apple and LinkedIn sign-ins. Password hashes (the scrambled form a provider stores instead of the password) come too, where BuildBase can check them, so those users keep their passwords.

It sends batches of 500, prints the totals and every row that failed, and skips users already there on a second run (--overwrite updates them). --dry-run converts and prints the first users without sending. It needs BUILDBASE_API_TOKEN. See Importing users.

content pull

buildbase content pull --out <file> fetches published content once and writes it to a JSON file, for a build step or CI. --modules and --collections narrow it, and --page-size sets the paging. It needs BUILDBASE_API_TOKEN. See Delivering content.

agent

MCP (Model Context Protocol) is the standard AI assistants such as Claude, ChatGPT and Cursor use to call tools in another app. If your app runs an MCP server with @buildbase/sdk/mcp (MCP and agents), three commands help you test it and get it listed:

CommandWhat it does
agent doctor --url <mcp-url>Connects the way an AI client does the first time, and reports what would go wrong (below)
agent install --url <mcp-url>Prints the install deeplinks, commands and config snippets for Cursor, VS Code, Claude Code, Claude, ChatGPT, Windsurf, Gemini CLI and Goose, ready for your own docs page
agent listing --url <mcp-url>Writes a listing kit from the running server: server.json for the official MCP Registry and checklists for the Claude directory and ChatGPT apps. Exits 1 while a required field is missing

agent doctor checks what an AI client meets on first contact:

  • The 401 challenge, the answer that tells a client it has to sign in first.
  • The protected-resource and authorization server metadata: the files that tell a client where and how to sign in with OAuth (the standard sign-in flow agents use to get access).
  • DNS rebinding protection, which stops a web page from reaching a server on your own machine.
  • How fast it answers (latency).
  • Every tool, against the Claude and ChatGPT directory rules.
  • A timed call of each read-only tool.
  • The site documents agents look for.

--json prints the result for CI, --strict fails on warnings, and --conformance and --inspector also run the official MCP test suites.

If your server needs sign-in, doctor reads its tools/list with a token from BUILDBASE_DOCTOR_TOKEN, taken from the environment only. How each client connects is in Connect an AI agent.

Next steps