CLI Overview

Install the Buildspace CLI, use the buildspace command, and manage your app lifecycle from the terminal.

The Buildspace CLI gives you a single terminal entrypoint for Buildspace app creation, local setup, deployment, and environment management.

Installation

npm install -g @buildspacestudio/cli

Or run directly with npx:

npx @buildspacestudio/cli --help

Confirmations and AI agents

Commands that delete data or change live behavior ask before they act (app delete, promote, env unset, domains remove, db delete, storage delete, pages delete, and similar).

In a terminal you get a prompt: [y/N], or type the name for irreversible actions.
Without a TTY (CI, scripts, AI agents) or with --json, the command makes no change and exits with code 3 and a Confirmation required message. With --json the error is {"error": "...", "code": "CONFIRMATION_REQUIRED"} on stderr.
Pass --yes (-y) to proceed. env set also takes --overwrite; app delete also takes --confirm <slug>.

AI agents should pass --yes only when you explicitly asked for that exact action; otherwise they should stop and ask you first.

Commands

Command	Description
`buildspace auth`	Login and manage personal access tokens
`buildspace app`	Create apps, choose the active app, manage hosting, billing, login branding, and dev preview sleep/wake, and read analytics (`insights`, `emails`, `users`, `report`)
`buildspace init`	Clone a Buildspace app repository
`buildspace deploy`	Check deployment status, history, and logs
`buildspace promote`	Roll the dev branch out to production
`buildspace env`	Manage environment variables
`buildspace domains`	Connect custom domains you own to your app
`buildspace pages`	Publish standalone HTML files to a hosted URL
`buildspace agent`	Inspect and drive the hosted AI dev agent
`buildspace db`	Manage standalone databases
`buildspace storage`	Manage standalone storage buckets and their files
`buildspace whoami`	Show the authenticated identity
`buildspace doctor`	Diagnose CLI version, auth, API reachability, and git remote
`buildspace update`	Update the CLI
`buildspace config`	Configure CLI settings

Default Flow

npm install -g @buildspacestudio/cli

buildspace auth login

buildspace app create --name "My App"

# note the generated slug from the create command output
buildspace init --app <generated-slug>
cd <generated-slug>
bun install

# Make changes, commit them, then deploy
buildspace deploy

buildspace app ... is the main app-management surface. Use it to create apps, select the active app, and inspect hosting state.

When you create an app without --slug, Buildspace generates one for you from the app name and adds a short suffix automatically if needed to avoid collisions.

See App Lifecycle for the full install -> auth -> create -> init -> develop -> deploy walkthrough.

App Resolution

Many commands need to know which app to target. The CLI resolves the app in this order:

--app <slug> flag (highest priority)
Git remote origin URL (parses the slug from the repo URL)
Active app set via buildspace app use <slug>

Machine-Readable Output

All key commands support a --json flag for machine-readable JSON output. This is useful for scripting and LLM integrations. See JSON Output for details.