Buildspace
CLI

App Management

Create, list, delete, and manage hosting for your Buildspace apps.

List Apps

buildspace app list

Shows all your apps with the active app marked.

buildspace app list --json

Returns JSON with apps and activeApp fields.

Show Current App

buildspace app current

Displays the currently resolved app and how it was determined (flag, git remote, or active selection).

Set Active App

buildspace app use <slug>

Sets the default app for commands when no --app flag is provided and you're not inside a Buildspace git repo.

Create an App

buildspace app create --name "My App"

Options

FlagDescription
--name <name>App display name (required)
--slug <slug>Optional slug override
--description <text>Optional description
--category <value>Optional category
--jsonOutput result as JSON and skip provisioning wait
--no-waitSkip provisioning wait (human output)

If you omit --slug, Buildspace generates one from the app name. When a generated slug is already taken, Buildspace retries with a similar slug plus a short four-character suffix.

The new app is automatically set as the active app. Initial API keys are displayed after creation.

In human mode, the CLI unblocks as soon as the repository is ready (~5–10s) and prints the buildspace init command immediately. Hosting, database, and storage finish in the background.

Use --json for scripting and agent pipelines — it exits immediately after the API call:

buildspace app create --name "My App" --json
{
  "app": { "id": "app_123", "slug": "my-app", "name": "My App" },
  "environments": [...],
  "keys": [{ "environment": "dev", "type": "secret", "key": "bs_secret_..." }],
  "provisioningSession": { "id": "ps_456", "status": "running" }
}

The provisioningSession.id can be used with buildspace app status to poll setup progress.

Typical next steps:

buildspace init --app <generated-slug>
cd <generated-slug>
bun dev

App Status

buildspace app status [<slug>] [--json]

Shows hosting status and a Terms & Privacy readiness checklist for an app. legal is null when the checklist can't be loaded. Checks are warnings only. Resolves the app from --app, a positional slug, the git remote, or the active app — same as other app commands.

{
  "app": { "id": "app_123", "slug": "my-app", "name": "My App" },
  "hosting": {
    "dev": { "status": "active", "url": "https://my-app.buildspace.dev" },
    "prod": { "status": "disabled", "url": null }
  },
  "legal": {
    "ready": false,
    "summary": "Add your Terms and Privacy Policy before real users sign up.",
    "checks": [
      { "key": "terms_url", "label": "Terms of Service linked", "status": "warn", "detail": "Add the URL under Login branding → Terms & privacy." },
      { "key": "privacy_url", "label": "Privacy Policy linked", "status": "ok", "detail": "https://my-app.com/privacy" }
    ]
  }
}

Delete an App

buildspace app delete <slug>

You are asked to type the slug to confirm. In scripts and agent sessions pass --yes (or --confirm <slug>, which must match the slug exactly). Optionally add --note <text> to record why the app was deleted.

Deleting an app cancels any in-flight AI build, then attempts hosting teardown for every environment (archiving the git repo and removing the Railway services, volumes, and domains) before soft-deleting the app record. Teardown is best-effort: if a step fails, the CLI prints a warning naming the environment so you can clean it up from the Studio hosting pane.

Hosting

Manage per-environment hosting for your app.

Check Status

buildspace app hosting status
buildspace app hosting status --env prod
buildspace app hosting status --json

Enable Hosting

buildspace app hosting enable --env dev

Disable Hosting

buildspace app hosting disable --env prod

All hosting subcommands accept --app <slug> and --env dev|prod (defaults to dev).

If you are already inside a cloned Buildspace app repo, you usually do not need --app because the CLI resolves the app from the git remote.

Dev Preview Sleep and Wake

The hosted dev preview sleeps when idle. app status shows when it is asleep.

buildspace app wake [--no-wait] [--json]
buildspace app sleep [--json]

wake starts the preview and waits until it is reachable (--no-wait returns right after requesting the wake). sleep puts it to sleep now instead of waiting for the idle timeout. Both accept --app <slug>.

Billing

buildspace app billing status [--env dev|prod] [--json]
buildspace app billing enable --env dev                   # requires Stripe Connect first (Studio Settings)
buildspace app billing overview [--json]                  # Stripe connection, readiness checklist, counts, recent activity
buildspace app billing products [--all] [--env dev|prod]  # products with their prices and ids
buildspace app billing products create --name "Pro" --amount 9.99 --interval month [--lookup-key pro-monthly]
buildspace app billing products create --name "Credits" --amount-cents 500 --type one_time
buildspace app billing products update <id|name> --name "Pro Plus" --description "..."   # or --clear-description
buildspace app billing products archive <id|name>         # remove: archives the product and deactivates its prices
buildspace app billing prices [--all]                     # flat price list
buildspace app billing prices create --product <id|name> --amount 290 --interval year   # add another price
buildspace app billing prices replace <priceId> --amount 39                             # change a price (see below)
buildspace app billing prices deactivate <priceId>        # or: activate, remove
buildspace app billing sync                               # copy dev products/prices into prod (no --env; prod billing must be enabled first)
buildspace app billing promos [--all]                     # this app's promotion codes
buildspace app billing promos create --code LAUNCH20 --percent-off 20 --max-redemptions 100 --expires 2026-12-31
buildspace app billing promos deactivate LAUNCH20         # or: activate, remove

products create makes the product and its first price together. --amount is in major units (9.99); use --amount-cents for zero-decimal currencies like JPY. Recurring products need --interval day|week|month|year. Set --lookup-key so app code can start checkout with createCheckout({ lookupKey }) instead of hardcoding a price id. All catalog commands accept --app <slug>, --env dev|prod (default dev) and --json.

Sync needs prod billing on: sync only promotes the dev catalog to production, so it fails until live Stripe is connected and buildspace app billing enable --env prod has run. You don't need it to use or verify the dev catalog (products --json).

Updating and removing: products can be renamed or re-described in place. Stripe prices are immutable, so prices replace creates a new price that inherits everything you don't override (including the lookup key, which moves to the new price) and deactivates the old one; existing subscribers stay on the old price. Stripe doesn't allow deleting products or prices that have been used, so "remove" means archive/deactivate. Archived products can't get new prices; create a new product instead.

Set up billing end to end (agents):

  1. buildspace app billing overview --json — confirm stripe.test is connected (the creator connects Stripe in Studio Settings; the CLI cannot do that step).
  2. buildspace app billing enable --env dev if environments[].enabled is false.
  3. buildspace app billing products create ... --json for each plan, then buildspace app billing products --json to verify. Fix mistakes with products update / prices replace rather than recreating.
  4. When ready for production: connect live Stripe, buildspace app billing enable --env prod, then buildspace app billing sync. Check readiness.checks in overview --json for anything still missing.

Login Branding

Customize the hosted login page for an app. Edits go to a draft; nothing is live until publish. Every command accepts --app <slug> and --json.

buildspace app branding show                       # draft vs published, and the live login URLs
buildspace app branding set --primary-color "#FF5A48" --headline "Welcome back" \
  --subheadline "Sign in to continue" --button-label "Email me a code" \
  --bullet "Fast" --bullet "Private" --heading-font "Fraunces" --style-preset clean --radius md
buildspace app branding set --clear primary-color,bullets   # back to defaults for those fields
buildspace app branding logo set ./logo.png                 # or an https:// URL; `logo remove`
buildspace app branding favicon set ./favicon.png           # png, svg, or ico
buildspace app branding design import ./design.md           # store design.md, extract suggestions
buildspace app branding design apply                        # apply the suggestions to the draft
buildspace app branding preview                             # 1-hour link that renders the DRAFT on the real login page
buildspace app branding publish --yes                       # make the draft live
buildspace app branding reset --yes                         # back to Buildspace defaults (draft and published)
  • Fields: --title --headline --subheadline --button-label --legal-addon, colors --primary-color --background-color --surface-color --text-color (#RRGGBB), --heading-font --body-font (from a supported list; the error names the valid ones), --style-preset buildspace|clean|minimal, --radius none|sm|md|lg, up to 3 --bullet (max 40 chars), --terms-url --privacy-url --terms-version (https only).
  • Images: logo up to 512 KB (png, jpg, webp, svg), favicon up to 128 KB (png, svg, ico). An uploaded file wins over a pasted URL.
  • Preview before publishing: run preview, open the sign-in or sign-up link, and check it. The link is unlisted, expires after an hour, and only works for that app. The sign-up page shows "closed" when the dev environment's sign-up mode is closed.
  • design import uses AI to extract suggestions from a design doc. It never changes the draft until design apply.
  • set on a fresh draft starts from the published values, so changing one field doesn't blank the rest.
  • Branding applies to the whole project, not per environment.

Analytics and Reports

Read-only commands for checking how an app is doing. Every one accepts --app <slug> and --json, so an AI agent can pull the data and summarize it.

buildspace app insights [--days 30]          # event totals, unique actors, top events
buildspace app emails [--days 30] [--limit 10]  # sent, delivery, open and click rates, recent sends
buildspace app users                         # app users and last logins
buildspace app report [--days 30]            # insights + emails + users + billing in one snapshot

--days accepts 1–365 (default 30). report returns each section independently, so one failing section is reported as { "error": "..." } while the others still return data.

buildspace app report --json
{
  "app": "my-app",
  "report": {
    "days": 30,
    "generatedAt": "2026-09-28T19:00:00.000Z",
    "insights": { "data": { "totalEvents": 1280, "uniqueActors": 96, "topEvents": [] } },
    "emails": { "data": { "totalSent": 7, "deliveryRate": 100 } },
    "users": { "data": { "total": 42, "users": [] } },
    "billing": { "data": { "environments": [] } }
  }
}

Deployment history and logs are under buildspace deploy.

Authentication

Sign in and manage personal access tokens with the Buildspace CLI.

Clone an App

Use buildspace init to clone a managed Buildspace app repository and pull local environment variables.

On this page

List AppsShow Current AppSet Active AppCreate an AppOptionsApp StatusDelete an AppHostingCheck StatusEnable HostingDisable HostingDev Preview Sleep and WakeBillingLogin BrandingAnalytics and Reports