Build with an AI agent

Zero-setup flow for AI coding agents. Authenticate with an env var, create a project non-interactively, and give your agent the full Buildspace context.

Quick start

The fastest path from "nothing" to "agent is building my app":

# 1. Verify your token (no login step)
BUILDSPACE_TOKEN=<pat> buildspace whoami --json

# 2. Create a project and capture the slug
BUILDSPACE_TOKEN=<pat> buildspace app create --name "My App" --json

# 3. Clone the repo and pull dev env vars
buildspace init --app <slug>

# 4. Give your agent full Buildspace context
npx skills add BuildSpaceStudio/skills

Get a PAT in Creator Studio → Settings → Tokens, or use the Start with AI panel on the Projects page to generate one and copy a ready-to-paste prompt.

Authenticate without logging in

Set BUILDSPACE_TOKEN instead of running buildspace auth login. The token takes priority over any saved config file.

BUILDSPACE_TOKEN=bs_pat_xxx buildspace app list

Two optional overrides for self-hosted or local deployments:

Env var	Purpose
`BUILDSPACE_TOKEN`	Personal access token
`BUILDSPACE_API_URL`	Override the API base URL
`BUILDSPACE_GIT_URL`	Override the Git base URL

Create a project non-interactively

--json returns structured output immediately and skips the provisioning wait. Use --no-wait for the same non-blocking behaviour without --json output.

BUILDSPACE_TOKEN=<pat> buildspace app create --name "My App" --json

{
  "app": { "id": "app_123", "slug": "my-app", "name": "My App" },
  "environments": [...],
  "keys": [...],
  "provisioningSession": { "id": "ps_456", "status": "running" }
}

The provisioningSession.id can be polled via buildspace app status <slug> if you need to wait for hosting/database setup before deploying.

In human mode (no --json), the CLI unblocks after the repository step is ready (~5–10s) and prints next steps immediately. Hosting, database, and storage finish in the background.

Verify auth before running commands

buildspace whoami --json
# or: buildspace auth status --json

{
  "authenticated": true,
  "authMethod": "pat",
  "apiUrl": "https://creator.buildspace.studio",
  "gitUrl": "https://api.buildspace.studio",
  "token": {
    "name": "AI Agent — 5/30/2026",
    "keyPrefix": "bs_pat_ab",
    "accessMode": "unrestricted",
    "apps": [],
    "expiresAt": "2026-08-28T00:00:00.000Z"
  }
}

Exit code 1 with { "authenticated": false, "code": "AUTH_REQUIRED" } when the token is missing or invalid.

Check app status

buildspace app status <slug> --json

{
  "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 }
  }
}

Machine-readable errors

When a command is called with --json and fails, the error is written to stderr as structured JSON:

{ "error": "App not found", "code": "NOT_FOUND" }

Code	When
`AUTH_REQUIRED`	401 / 403 — token missing, expired, or revoked
`NOT_FOUND`	404 — app or resource does not exist
`ALREADY_EXISTS`	409 — slug or resource already taken
`PROVISIONING_FAILED`	Provisioning reached a failed terminal state
`NETWORK_ERROR`	Fetch failure or unexpected 5xx

Give your agent the full SDK context

npx skills add BuildSpaceStudio/skills

This installs Buildspace skills for Claude Code, Codex, or any AI coding agent — giving it context about the SDK, services, and API patterns.

Full reference

https://docs.buildspace.studio/llms.txt — machine-readable index of all docs, aggregated for agent consumption. llms-full.txt inlines every page into a single file.

On this page