# 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. ```bash 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 --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 | Command | What it does | In `@buildbase/sdk` | | ---------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | [`init`](#init) | Wire the SDK into the app in this folder | 0.0.79 and later | | [`content pull`](#content-pull) | Fetch published content to a JSON file | 0.0.73 and later | | [`import`](#import) | Import users from Clerk, Auth0, Firebase or Supabase | 0.0.90 and later | | [`login`, `logout`](#login-and-logout) | Sign this machine in to your console with a device code | 1.0.0 and later | | [`init --dev`, `env`](#environments) | Point the app at a development or staging environment, and promote changes | 1.0.0 and later | | [`blueprint`](#blueprint) | Set up a whole organization from one JSON file, and serve it to coding agents | 1.0.0 and later | | [`agent doctor`, `install`, `listing`](#agent) | Check your MCP server, print install links for every client, write listing files | 1.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](/quick-start/installation#or-let-the-cli-write-these-files). | Option | What it does | | ---------------------- | ----------------------------------------------------------------------------------------- | | `--framework ` | `nextjs`, `vite` or `express`; detected from `package.json` when left out | | `--org-id <24 hex>` | Your organization id from the console | | `--server-url ` | The API server; the cloud one by default | | `--client-id ` | The sign-in client's id | | `--redirect-url ` | Where sign-in returns to; the app's local address by default | | `--no-install` | Skip `npm install` of the SDK | | `--yes` | Take every prompt's default (an empty folder becomes a Next.js app) | | `--dev` | Wire the app to your development environment, client secret included. Needs `login` first | | `--env ` | With `--dev`: the environment to wire, by name or key (Development by default) | | `--rotate-secret` | With `--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. | Option | What it does | | --------------------- | ------------------------------------------------------------- | | `--open` | Open the approval page in your browser | | `--json` | Print the outcome as one JSON document, without the token | | `--central-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](/quick-start/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. | Command | What it does | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `init --dev` | Wire the app to Development (or `--env `) with no console step | | `env list` | Your organization's environments, with their keys | | `env use ` | Point `.env.local` at one; with `--rotate-secret`, a new client secret | | `env create ` | Add an environment (owner or admin, within your plan) and point `.env.local` at it, client secret included | | `env diff ` | What pushing its unsubscribe groups, email templates, workflows, plans and plan groups to production would change, item by item | | `env push ` | 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 ` | 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 ` 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](/blueprints/cli) covers it step by step. | Subcommand | What 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 | | `export` | Write the organization's current setup as a blueprint, secrets as `${env:NAME}` placeholders | | `schema` | Write the JSON Schema, for editors and AI agents | | `mcp` | Serve these as tools to a coding agent over stdio ([AI agents](/blueprints/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 ` 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](/authentication/importing-users). ## content pull `buildbase content pull --out ` 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](/content/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](/reference/mcp-agents)), three commands help you test it and get it listed: | Command | What it does | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent doctor --url ` | Connects the way an AI client does the first time, and reports what would go wrong (below) | | `agent install --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 ` | 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](/agents/connect-an-agent). ## Next steps - [Installation](/quick-start/installation) - what `init` writes, file by file - [Development and staging environments](/quick-start/environments) - `init --dev` and the `env` commands in context - [Connect an AI agent](/agents/connect-an-agent) - add your MCP server to every agent client