App Lifecycle

This is the default Buildspace CLI flow for both humans and coding agents.

1. Install the CLI

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

If you do not want a global install, you can also run the package directly:

npx @buildspacestudio/cli --help

2. Authenticate

Use browser login for interactive local setup:

buildspace auth login

Or store a personal access token directly:

buildspace auth set --token <your-pat>

3. Create the app

buildspace app create --name "My App" --description "My first Buildspace app"

This creates the app, auto-generates a slug, and sets it as your active app in the CLI.

Save the returned slug from the command output or JSON response. You will use it for buildspace init.

4. Clone the app locally

buildspace init --app <generated-slug> --dir ./<generated-slug>
cd <generated-slug>
bun install

buildspace init clones the managed app repository and pulls the development environment variables into .env.local when available.

5. Develop locally

bun dev

The exact local workflow depends on the starter repo you cloned, but bun install and bun dev are the standard defaults.

6. Deploy development changes

git add -A
git commit -m "Build initial app"
buildspace deploy

buildspace deploy pushes your current HEAD to origin/main, which triggers a development deployment.

7. Check deployment status

buildspace deploy status
buildspace deploy logs --env dev --latest
buildspace app hosting status --env dev

Use buildspace app hosting status when you want the current environment URL, and buildspace deploy status when you want deployment history.

App Resolution Rules

Commands that target an app resolve it in this order:

1. --app <slug>
2. current git remote origin
3. active app selected with buildspace app use <slug>

That means the easiest workflow after buildspace init is to run app-scoped commands from inside the cloned repo.