@buildspacestudio/cli

BuildSpace CLI for creating apps, cloning repos, managing env vars, and triggering deployments from your terminal.

Install

Requires Node.js 18+.

npm install -g @buildspacestudio/cli
buildspace --help

What it does

• Sign in with browser-based login or a personal access token
• Create and select BuildSpace apps
• Clone an app repo locally
• Manage dev and prod environment variables
• Enable hosting and inspect hosting state
• Trigger deployments and stream deployment logs

Quick start

# 1) Authenticate
buildspace auth login

# 2) Create an app
buildspace app create --name "My App"

# 3) Clone it locally
buildspace init --app my-app

# 4) Pull local env vars
buildspace env pull --env dev

# 5) Deploy current HEAD to dev
buildspace deploy

Commands

auth

Manage authentication for CLI requests.

buildspace auth login
buildspace auth set --token <bs_pat_...>
buildspace auth show
buildspace auth clear

• login opens a browser, completes a PKCE flow, and stores a token locally
• set stores a personal access token manually
• show prints the masked token and active API/git endpoints
• clear removes the stored token

Useful options:

buildspace auth login --url https://creator.buildspace.studio --git-url https://api.buildspace.studio
buildspace auth login --no-open
buildspace auth login --name "CLI on laptop" --expires-days 30

app

Create apps, switch active app context, and manage hosting.

buildspace app list
buildspace app current
buildspace app use <slug>
buildspace app create --name "My App"
buildspace app delete <slug> --confirm <slug>
buildspace app hosting status [--app <slug>] [--env dev|prod]
buildspace app hosting enable [--app <slug>] [--env dev|prod]
buildspace app hosting disable [--app <slug>] [--env dev|prod]

Notes:

• app create sets the new app as your active app automatically
• app delete is a soft delete and requires --confirm to match the slug exactly
• hosting commands default to the resolved app from --app, git remote, or active app

config

Inspect or override the API and git base URLs used by the CLI.

buildspace config show
buildspace config set-url --url <api-base-url> [--git-url <git-base-url>]
buildspace config reset

init

Clone a BuildSpace app repo by slug.

buildspace init --app <slug>
buildspace init --app <slug> --dir ./my-local-folder

After cloning, the CLI changes its working directory to the clone and runs the same flow as buildspace env pull for dev (writes .env.local). Your interactive shell does not change—use the printed cd path to enter the project.

env

Manage environment variables for an app.

buildspace env list [--env dev|prod]
buildspace env set KEY=VALUE [--env dev|prod] [--secret | --no-secret]
buildspace env unset KEY [--env dev|prod]
buildspace env pull [--env dev|prod] [--output .env.local]

Behavior:

• list shows masked values
• set creates or updates a variable, and uppercases the key automatically
• pull writes system vars plus non-secret vars to a local env file
• keys with the BUILDSPACE_ prefix are reserved
• NEXT_PUBLIC_* keys default to non-secret unless you override them

Examples:

buildspace env list --env prod
buildspace env set STRIPE_SECRET_KEY=sk_test_123 --secret
buildspace env set NEXT_PUBLIC_API_URL=https://example.com --no-secret
buildspace env pull --env dev --output .env.local

deploy

Deploy from the current repo and inspect deployment state.

buildspace deploy
buildspace deploy status
buildspace deploy history --env prod --limit 5
buildspace deploy logs --env dev --latest
buildspace deploy logs --env prod --deployment <deployment-id>

• deploy pushes HEAD to origin/main to trigger a dev deployment
• status shows the latest deployment summary for dev, prod, or both
• history shows recent deployment history for dev, prod, or both
• logs shows deployment logs for a specific deployment or the latest one

telemetry

Manage anonymous product telemetry preferences.

buildspace telemetry status
buildspace telemetry enable
buildspace telemetry disable

• status shows whether telemetry is enabled and the anonymous installation ID
• enable turns on anonymous telemetry (default)
• disable turns off all telemetry data collection

Telemetry can also be disabled globally via the environment variable:

export BUILDSPACE_TELEMETRY=0

Telemetry is anonymous, fire-and-forget, and never blocks CLI commands. See the telemetry docs for details on what is collected.

App resolution

Most app-aware commands resolve the target app in this order:

1. --app <slug>
2. the current git remote origin
3. the active app saved by buildspace app use

That means commands like buildspace env list and buildspace deploy status usually work directly inside a cloned BuildSpace app repo.

Local config

The CLI stores local settings such as:

• personal access token
• API base URL
• git base URL
• active app selection

You can inspect the current configuration at any time with:

buildspace config show

Help

Run help for any command group:

buildspace --help
buildspace auth --help
buildspace app --help
buildspace env --help
buildspace deploy --help

Links

• Docs: https://docs.buildspace.studio/docs/cli/overview
• Repository: https://github.com/buildspacestudio/buildspace/tree/main/packages/cli