base44 · claude · Aug 4, 2026
diff --git a/CLI_VERSION b/CLI_VERSION
@@ -1 +1 @@
-v0.1.7
+v0.1.8
diff --git a/skills/base44-cli/SKILL.md b/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.1.8
 ---
 
 # Base44 CLI
@@ -179,7 +179,7 @@ my-app/
 | `agentSkillsDir` | Directory for agent skill instructions | `"agent-skills"` |
 | `connectorsDir` | Directory for connector configs | `"connectors"` |
 | `site.installCommand` | Command to install dependencies | - |
-| `site.buildCommand` | Command to build the project | - |
+| `site.buildCommand` | Command to build the project; used by `base44 build` and `base44 deploy`/`base44 site deploy --build` (runs with `VITE_BASE44_APP_ID` set) | - |
 | `site.serveCommand` | Command to run dev server | - |
 | `site.outputDirectory` | Build output directory for deployment | - |
 
@@ -274,7 +274,8 @@ Workspaces (a.k.a. organizations) group apps under shared membership. By default
 
 | Command | Description | Reference |
 |---------|-------------|-----------|
-| `base44 deploy` | Deploy all resources (entities, functions, agents, agent skills, connectors, auth config, and site) | [deploy.md](references/deploy.md) |
+| `base44 build` | Build the site with the app id injected (`VITE_BASE44_APP_ID`), without deploying | [build.md](references/build.md) |
+| `base44 deploy` | Deploy all resources (entities, functions, agents, agent skills, connectors, auth config, and site); can build the site first with `--build`/`--no-build` | [deploy.md](references/deploy.md) |
 
 ### Entity Management
 

diff --git a/skills/base44-cli/references/build.md b/skills/base44-cli/references/build.md
@@ -0,0 +1,50 @@
+# base44 build
+
+Build the site with the Base44 app id injected.
+
+## Syntax
+
+```bash
+npx base44 build
+```
+
+## Options
+
+This command takes no options.
+
+## What It Does
+
+1. Requires a linked local project (`base44/.app.jsonc` must exist)
+2. Reads `site.buildCommand` from `base44/config.jsonc`
+3. Runs that build command with the environment variable `VITE_BASE44_APP_ID` set to the linked app's id
+4. Fails with a config error if `site.buildCommand` is not set
+
+## Examples
+
+```bash
+# Build the site with the app id injected as VITE_BASE44_APP_ID
+npx base44 build
+```
+
+## Requirements
+
+- Must be run from a linked Base44 project directory (`base44/.app.jsonc` must exist)
+- `site.buildCommand` must be configured in `base44/config.jsonc`, e.g.:
+  ```jsonc
+  "site": {
+    "buildCommand": "npm run build",
+    "outputDirectory": "./dist"
+  }
+  ```
+
+## Notes
+
+- This is the same build step that `base44 deploy` and `base44 site deploy` can run for you via `--build` — use `base44 build` directly when you want to build without deploying
+- Vite projects should read `import.meta.env.VITE_BASE44_APP_ID` to get the app id at build time
+
+## Related Commands
+
+| Command | Description |
+|---------|-------------|
+| `base44 deploy` | Deploy all project resources (can build first with `--build`) |
+| `base44 site deploy` | Deploy only the site (can build first with `--build`) |
diff --git a/skills/base44-cli/references/deploy.md b/skills/base44-cli/references/deploy.md
@@ -13,6 +13,8 @@ npx base44 deploy [options]
 | Option | Description |
 |--------|-------------|
 | `-y, --yes` | Skip confirmation prompt |
+| `--build` | Build the site before deploying (skips the prompt) |
+| `--no-build` | Deploy without building (skips the prompt) |
 
 ## What It Deploys
 
@@ -55,7 +57,8 @@ npx base44 deploy -y
 2. Detects available resources (entities, functions, 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 a site is configured with `site.buildCommand`, builds it (see [Build Before Deploy](#build-before-deploy))
+6. Deploys all resources in sequence:
    - Sets app visibility (if configured)
    - Pushes entity schemas
    - Deploys functions
@@ -64,8 +67,19 @@ 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)
+
+## Build Before Deploy
+
+If `site.outputDirectory` is configured, `deploy` can build the site for you before uploading it:
+
+- `--build`: always builds first (runs `site.buildCommand` with `VITE_BASE44_APP_ID` injected), and errors out if `site.buildCommand` isn't configured
+- `--no-build`: never builds, deploys whatever is already in `site.outputDirectory`
+- Neither flag, interactive mode, `site.buildCommand` configured: asks "Build the site first?"
+- Neither flag, non-interactive mode (or no `site.buildCommand`): skips building silently
+
+This is the same build step as running `base44 build` separately.
 
 ## Connector OAuth Flow
 
@@ -79,7 +93,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 configure `site.buildCommand` so `deploy` can build it for you, or build it yourself before running `deploy --no-build`
 
 ## Output
 
@@ -91,12 +105,13 @@ After successful deployment:
 
 - If no resources are found, the command exits with a message
 - Use individual commands (`entities push`, `functions 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
+- In non-interactive mode (`-y`), the site is not built unless `--build` is also passed
 
 ## Related Commands
 
 | Command | Description |
 |---------|-------------|
+| `base44 build` | Build the site (with the app id injected) without deploying |
 | `base44 entities push` | Push only entities |
 | `base44 functions deploy` | Deploy only functions |
 | `base44 agents push` | Push only agents |

diff --git a/skills/base44-cli/references/site-deploy.md b/skills/base44-cli/references/site-deploy.md
@@ -14,6 +14,7 @@ Deploy built site files to Base44 hosting.
 - [Error Handling](#error-handling)
 - [Use Cases](#use-cases)
 - [Notes](#notes)
+- [Related Commands](#related-commands)
 
 ## Syntax
 
@@ -26,13 +27,37 @@ npx base44 site deploy [options]
 | Option       | Description               |
 | ------------ | ------------------------- |
 | `-y, --yes`  | Skip confirmation prompt  |
+| `--build` | Build the site before deploying (skips the prompt) |
+| `--no-build` | Deploy without building (skips the prompt) |
 
 Use `-y` flag for non-interactive/automated deployments:
 
 ```bash
 npx base44 site deploy -y
 ```
 
+### Build Before Deploy
+
+If `site.outputDirectory` is configured, `site deploy` can build the site for you first:
+
+- `--build`: always builds first (runs `site.buildCommand` with `VITE_BASE44_APP_ID` injected), and errors out if `site.buildCommand` isn't configured
+- `--no-build`: never builds, deploys whatever is already in `site.outputDirectory`
+- Neither flag, interactive mode, `site.buildCommand` configured: asks "Build the site first?"
+- Neither flag, non-interactive mode (or no `site.buildCommand`): skips building silently
+
+This is the same build step as running `base44 build` separately.
+
+### Experimental: Deployments API (`--git-hash`, `--concurrency`)
+
+These options only appear in `--help` and are only accepted when the environment variable `BASE44_STATIC_DEPLOYMENTS` is set to `1` or `true`. Without the env var, passing them fails with an unknown-option error. Treat this as an experimental, opt-in code path, not the default deploy flow.
+
+| Option | Description |
+|--------|-------------|
+| `--git-hash <hash>` | Commit the build came from (7-64 hex chars); deploys through the deployments API instead of the legacy tarball upload |
+| `--concurrency <n>` | Parallel asset uploads (whole number, default and max defined by the CLI internals) |
+
+When `--git-hash` is passed, `site deploy` uploads only new/changed static assets (deduped against what's already stored for the app) and creates a deployment tied to that commit, instead of archiving and uploading the whole output directory. The resulting deployment has no public URL of its own — what production serves is still decided by publishing the app from the Base44 builder.
+
 ## Authentication
 
 **Required**: Yes. If not authenticated, you'll be prompted to login first.
@@ -41,17 +66,18 @@ npx base44 site deploy -y
 
 - Must be run from a Base44 project directory
 - Project must have `site.outputDirectory` configured in project config
-- Site must be built before deploying (run your build command first)
+- Site must be built before deploying — either configure `site.buildCommand` so `site deploy` can build it for you (see [Build Before Deploy](#build-before-deploy)), or build it yourself first
 - **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).
 
 ## How It Works
 
 1. Reads project configuration
 2. Validates that site configuration exists
 3. Prompts for deployment confirmation showing the output directory
-4. Creates an archive of site files from the output directory
-5. Deploys to Base44 hosting
-6. Returns the app URL
+4. Builds the site first if requested (see [Build Before Deploy](#build-before-deploy))
+5. Creates an archive of site files from the output directory
+6. Deploys to Base44 hosting
+7. Returns the app URL
 
 ## Interactive Flow
 
@@ -111,8 +137,15 @@ Deployment cancelled
 
 ## Notes
 
-- Always build your site before deploying
+- Always build your site before deploying (or pass `--build` to have `site deploy` do it for you)
 - The command deploys whatever is in your output directory
 - Make sure your build completed successfully before deploying
 - Previous deployments are preserved (versioned) in Base44
 - Deployment is immediate and updates your live site
+
+## Related Commands
+
+| Command | Description |
+|---------|-------------|
+| `base44 build` | Build the site (with the app id injected) without deploying |
+| `base44 deploy` | Deploy all project resources, including the site |