@buildspacestudio/cli 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,194 @@
+# @buildspacestudio/cli
+
+BuildSpace CLI for creating apps, cloning repos, managing env vars, and triggering deployments from your terminal.
+
+## Install
+
+Requires Node.js 18+.
+
+```bash
+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
+
+```bash
+# 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.
+
+```bash
+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:
+
+```bash
+buildspace auth login --url https://runtime.buildspace.studio --git-url https://runtime.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.
+
+```bash
+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.
+
+```bash
+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.
+
+```bash
+buildspace init --app <slug>
+buildspace init --app <slug> --dir ./my-local-folder
+```
+
+After cloning, the CLI attempts to pull dev env vars into `.env.local` automatically when possible.
+
+### `env`
+
+Manage environment variables for an app.
+
+```bash
+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:
+
+```bash
+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.
+
+```bash
+buildspace deploy
+buildspace deploy status
+buildspace deploy status --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 recent deployments for dev, prod, or both
+- `logs` shows deployment logs for a specific deployment or the latest one
+
+## 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:
+
+```bash
+buildspace config show
+```
+
+## Help
+
+Run help for any command group:
+
+```bash
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildspacestudio/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Buildspace CLI for app creation, setup, deployment, and environment management",
   "license": "MIT",
   "repository": {