Update base44-cli skill to v0.2.2 October 25, 2026 12:22 PM UTC

CLI_VERSION

@@ -1 +1 @@
-v0.1.7
+v0.2.2

skills/base44-cli/SKILL.md

@@ -4,7 +4,7 @@ description: "The base44 CLI is used for EVERYTHING related to base44 projects:
 metadata:
   sourcePackage:
     name: base44
-    version: 0.1.7
+    version: 0.2.2
 ---
 
 # Base44 CLI
@@ -232,6 +232,14 @@ Do **not** use `--app-id` for commands that need local project files:
 - `base44 dev` runs from a linked local project, so it rejects `--app-id`
 - `base44 deploy` still requires a local project directory because it reads local resources
 
+## Global `--branch` Option
+
+`--branch <name>` targets a sandbox command (`sandbox read/write/edit/grep/ls/run/checkpoint`) at one of the app's branches by exact name, instead of `main`. Every other command rejects it outright — it is not a general way to read another branch's data. Run `npx base44 branches list --app-id <id> --json` to discover the names a given app has (`main` plus any active branch). Sandbox commands are documented in the base44-sandbox skill; this skill only owns `branches list`.
+
+| Command | Description | Reference |
+|---------|-------------|-----------|
+| `base44 branches list` | List main and active branch names for use with `--branch` | [branches-list.md](references/branches-list.md) |
+
 ## Global `--json` Option
 
 The CLI has a global `--json` option that makes commands emit a machine-readable JSON document on stdout instead of human-oriented output. It also forces non-interactive mode (spinners/status messages/logs move to stderr), so stdout stays pure JSON — safe to pipe into `jq` or another program.
@@ -552,13 +560,17 @@ Run one-off scripts against your app with the Base44 SDK pre-authenticated. Use
 
 ### Site Management
 
-| Command              | Description                               | Reference                                   |
-| -------------------- | ----------------------------------------- | ------------------------------------------- |
-| `base44 site deploy` | Deploy built site files to Base44 hosting | [site-deploy.md](references/site-deploy.md) |
-| `base44 site open`   | Open the deployed site in your browser    | [site-open.md](references/site-open.md)     |
+| Command               | Description                                                              | Reference                                     |
+| --------------------- | ------------------------------------------------------------------------- | ---------------------------------------------- |
+| `base44 site deploy`  | Deploy built site files to Base44 hosting                                 | [site-deploy.md](references/site-deploy.md)   |
+| `base44 site install` | Install the site's dependencies with its configured command, nothing else | [site-install.md](references/site-install.md) |
+| `base44 site dev`     | Run only the site's dev server, with no local backend                     | [site-dev.md](references/site-dev.md)         |
+| `base44 site open`    | Open the deployed site in your browser                                    | [site-open.md](references/site-open.md)       |
 
 **SPA only**: Base44 hosting supports Single Page Applications with a single `index.html` entry point. All routes are served from `index.html` (client-side routing).
 
+`site install` and `site dev` are local-only (no login, no app id) — the shape a hosted build/dev sandbox needs. Use plain `base44 dev` for ordinary local development (it also runs the backend); use `site dev` only when something else is already serving the backend and you need the frontend alone.
+
 ### Any Other API Operation
 
 For a Base44 platform task with no dedicated command above (custom domains, URL redirects, SEO settings, app users, collaborators and ownership, analytics, security scans, workspace members and groups, CSV imports, and more), find and call the public API endpoint directly with `base44 api`. It covers the Apps API and Workspace API with your CLI login, through the server's OpenAPI spec.

skills/base44-cli/references/branches-list.md

@@ -0,0 +1,62 @@
+# base44 branches list
+
+List an app's main and active branch names, for use with the global `--branch` option.
+
+## Syntax
+
+```bash
+npx base44 branches list [options]
+```
+
+## Options
+
+This command takes no command-specific options. It accepts the global `--app-id <id>` and `--json` options.
+
+## Authentication
+
+**Required**: Yes. If not authenticated, you'll be prompted to login first.
+
+## What It Does
+
+1. Fetches the app's active branches from the server
+2. Prepends `main` (always present, always listed first) to the fetched branches
+3. Prints each branch's name and status
+
+## Examples
+
+```bash
+# List branches for the linked local project
+npx base44 branches list
+
+# List branches for a specific app without a local checkout
+npx base44 branches list --app-id app_123 --json
+```
+
+## Output
+
+Human-readable:
+```bash
+$ npx base44 branches list
+main (active)
+feature-x (active)
+└ 2 branches
+```
+
+With `--json`:
+```json
+{"branches":[{"name":"main","status":"active"},{"name":"feature-x","status":"active"}]}
+```
+
+## Notes
+
+- This is a read-only, discovery-only command — it does not create, delete, or switch branches
+- The names it returns are exactly what the global `--branch <name>` option accepts; `--branch` resolves names within the selected app, and an unknown or ambiguous name fails
+- `--branch` only targets sandbox commands (`sandbox read/write/edit/grep/ls/run/checkpoint`) — every other command rejects it. Omitting `--branch`, or passing `--branch main`, targets `main`
+- `--app-id app_123 --json` is the shape an agent working outside the Builder UI uses to resolve branch names for a given app before targeting one with `--branch`
+
+## Related Commands
+
+| Command | Description |
+|---------|-------------|
+| `base44 sandbox read` | Read a file from the sandbox (or a branch, with `--branch`) |
+| `base44 sandbox write` | Write a file in the sandbox (or a branch, with `--branch`) |

skills/base44-cli/references/deploy.md

@@ -13,6 +13,9 @@ npx base44 deploy [options]
 | Option | Description |
 |--------|-------------|
 | `-y, --yes` | Skip confirmation prompt |
+| `--build` | Build the site first (skips the interactive "build first?" prompt) |
+| `--no-build` | Deploy without building (skips the prompt) |
+| `--git-hash <hash>` | Deploy the site by the commit the build came from, through the deployments API (advanced — see [Deploying by Commit](site-deploy.md#deploying-by-commit---git-hash)) |
 
 ## What It Deploys
 
@@ -56,7 +59,8 @@ npx base44 deploy -y
 2. Detects available resources (entities, functions, actors, agents, agent skills, connectors, site)
 3. Shows a summary of what will be deployed
 4. Asks for confirmation (unless `-y` flag is used)
-5. Deploys all resources in sequence:
+5. If the project has a `site.buildCommand`, asks whether to build first (interactive), or builds/skips immediately per `--build`/`--no-build` (non-interactive-safe)
+6. Deploys all resources in sequence:
    - Sets app visibility (if configured)
    - Pushes entity schemas
    - Deploys functions
@@ -66,8 +70,8 @@ npx base44 deploy -y
    - Pushes auth configuration
    - Pushes connector configurations
    - Uploads site files
-6. Handles OAuth authorization for any new connectors that require it
-7. Displays the dashboard URL and app URL (if site was deployed)
+7. Handles OAuth authorization for any new connectors that require it
+8. Displays the dashboard URL and app URL (if site was deployed)
 
 ## Connector OAuth Flow
 
@@ -81,7 +85,7 @@ Some connectors still require authorization. Run 'base44 connectors push' or ope
 
 - Must be run from a linked Base44 project directory
 - Must be authenticated (run `npx base44 login` first)
-- For site deployment, must run `npm run build` first
+- For site deployment, either build first (`npm run build`, or let `deploy` build for you via the prompt / `--build`) or pass `--no-build` to deploy whatever is already in the output directory
 
 ## Output
 
@@ -93,7 +97,8 @@ After successful deployment:
 
 - If no resources are found, the command exits with a message
 - Use individual commands (`entities push`, `functions deploy`, `actors deploy`, `agents push`, `agent-skills push`, `connectors push`, `site deploy`) if you only want to deploy specific resources
-- The site must be built before deployment - this command does not run `npm run build` for you
+- When the project has a `site.buildCommand`, interactive runs ask whether to build first; `--build`/`--no-build` pre-answer that prompt so it's safe to script
+- `--git-hash <hash>` is an advanced flag: it ships the site through the deployments API (the same lane `base44 site deploy --git-hash` uses) and publishes it, addressed by that commit. Without it, the site deploys through the archive upload and goes live as before — a full-stack build (one with a Cloudflare Worker) **requires** `--git-hash`, since the archive upload can't carry its worker
 
 ## Related Commands
 

skills/base44-cli/references/dev.md

@@ -61,6 +61,8 @@ If `site.serveCommand` is missing, `base44 dev` still works, but it only starts
 wired to your app's **production** backend — every read and write hits live data. Use it to develop
 the UI against real content; default to plain `base44 dev` otherwise.
 
+`--port` applies to the local backend, which `--remote` does not start — combining them fails with an error. Fails outright (no fallback) if the project has no `site.serveCommand`, since there'd be nothing to run.
+
 ## Examples
 
 ```bash

skills/base44-cli/references/eject.md

@@ -50,7 +50,7 @@ When you run `eject`:
 3. **Download**: The project code is downloaded to the specified path
 4. **New Project Creation**: A copy of the project is created in Base44 (e.g., "My App Copy")
 5. **Linking**: The local code is linked to the new project
-6. **Optional Deployment**: If the project has build commands configured, you'll be asked if you want to deploy
+6. **Optional Deployment**: If the project has a `site` block configured, you'll be asked if you want to deploy (both the install and build commands default to the conventions `base44 create` scaffolds, so a partial `site` block — e.g. only `outputDirectory` set — still offers this)
    - Runs the install command (e.g., `npm install`)
    - Runs the build command (e.g., `npm run build`)
    - Deploys all resources with `base44 deploy`

skills/base44-cli/references/exec.md

@@ -15,15 +15,17 @@ echo "<code>" | npx base44 exec [options]
 |--------|-------------|----------|---------|
 | `--local` | Run against the local `base44 dev` server instead of the deployed app | No | `false` |
 | `--port <number>` | Port the local dev server is on. Only valid with `--local` | No | `4400` |
-| `--privileged` | Run with admin privileges (bypass RLS). Requires app owner/editor role | No | `false` |
-| `--data-env <environment>` | Data environment to run against (e.g. `dev`, `prod`) | No | - |
+| `--privileged` | Run with admin privileges (bypass RLS). Requires app owner/editor role. Env: `BASE44_PRIVILEGED` | No | `false` |
+| `--data-env <environment>` | Data environment to run against (e.g. `dev`, `prod`). Env: `BASE44_DATA_ENV` | No | - |
 
 ## How It Works
 
 The `exec` command reads a script from stdin and runs it server-side with the Base44 SDK pre-authenticated as the currently logged-in user. This allows you to run one-off scripts against your app's data without writing a full function.
 
 By default the script runs against your deployed app. Pass `--local` to run it against a `base44 dev` server running on your machine instead — useful for testing scripts before they touch production data.
 
+`exec` loads an SDK version released within the last 24 hours, rather than holding back on Deno's default minimum-dependency-age window the way other imported npm packages do — so a script always gets a current SDK. Pin an exact version with `BASE44_EXEC_SDK_VERSION` (e.g. `0.8.52`) if you need reproducibility.
+
 ## Available Globals
 
 > **`base44`** — a preinitialized SDK client, available as a global variable in every exec script. You do not need to import or configure it — it is ready to use immediately.
@@ -81,6 +83,10 @@ echo "..." | npx base44 exec --data-env prod
 - Defaults to port `4400` (the same default `base44 dev` binds to); pass `--port` if you started `base44 dev` on a different port
 - `base44 dev` must already be running in another terminal — `exec --local` does not start it for you
 
+## Environment-Supplied Target (Advanced)
+
+Setting both `BASE44_EXEC_ACCESS_TOKEN` and `BASE44_EXEC_SERVER_URL` points `exec` at that server with that token directly, skipping the platform login entirely (`BASE44_EXEC_SERVICE_TOKEN` is forwarded alongside, if set). This is for a host that already has credentials of its own to hand the script — e.g. a platform-managed sandbox — not something to set for ordinary interactive use. The two required vars must be set together; setting only one is an error. This target cannot be combined with `--local`.
+
 ## Notes
 
 - The script runs with the Base44 SDK pre-authenticated — you can use `base44.entities`, `base44.functions`, etc. directly

skills/base44-cli/references/link.md

@@ -73,7 +73,7 @@ npx base44 link --create --name my-app --workspace 507f1f77bcf86cd799439011
    - Links to an existing app (with `--app-id` or interactive selection)
 4. Writes the app ID to `base44/.app.jsonc`
 
-The interactive selection (and `--app-id`) lists **all** of your existing Base44 apps, including ones originally built in the Base44 editor — not just apps previously created via the CLI.
+The interactive selection lists **all** of your existing Base44 apps, including ones originally built in the Base44 editor — not just apps previously created via the CLI. `--app-id` skips that listing entirely and links directly — the first request made is one that addresses the app by that ID, so a wrong ID fails immediately rather than after fetching a list. This also means `--app-id` works with a workspace API key (`BASE44_API_KEY`), which cannot list apps at all and would otherwise fail `link` in CI.
 
 ## Requirements