base44 · claude · Jun 28, 2026
diff --git a/CLI_VERSION b/CLI_VERSION
@@ -1 +1 @@
-v0.0.56
+v0.1.0
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.0.56
+    version: 0.1.0
 ---
 
 # Base44 CLI
@@ -345,6 +345,7 @@ Connectors let your app connect to external services (Google Calendar, Slack, St
 | ---------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
 | Create Connectors                  | Define connectors in `base44/connectors` folder      | [connectors-create.md](references/connectors-create.md)             |
 | `base44 connectors list-available` | List all available integration types from Base44     | [connectors-list-available.md](references/connectors-list-available.md) |
+| `base44 connectors initiate --integration-type <type>` | Initialize a single connector and start its OAuth flow (works with `--app-id`) | [connectors-initiate.md](references/connectors-initiate.md) |
 | `base44 connectors pull`           | Pull remote connectors to local files                | [connectors-pull.md](references/connectors-pull.md)                 |
 | `base44 connectors push`           | Push local connectors to Base44                      | [connectors-push.md](references/connectors-push.md)                 |
 
@@ -398,6 +399,20 @@ Manage project secrets (environment variables stored securely in Base44). These
 | `base44 secrets set` | Set one or more secrets (KEY=VALUE or --env-file) | [secrets-set.md](references/secrets-set.md) |
 | `base44 secrets delete <key>` | Delete a secret by name | [secrets-delete.md](references/secrets-delete.md) |
 
+### Remote Development (Sandbox)
+
+Develop an app remotely via its server-side sandbox. All sandbox commands require an app context (`--app-id`, `BASE44_APP_ID`, or a linked project) and output JSON.
+
+| Command | Description | Reference |
+|---------|-------------|-----------|
+| `base44 sandbox ls [path]` | List directory entries in the remote sandbox | [sandbox-ls.md](references/sandbox-ls.md) |
+| `base44 sandbox read <paths...>` | Read file contents from the remote sandbox | [sandbox-read.md](references/sandbox-read.md) |
+| `base44 sandbox write <path>` | Create or overwrite a file in the remote sandbox | [sandbox-write.md](references/sandbox-write.md) |
+| `base44 sandbox edit <path>` | Apply exact old→new string edits to a file | [sandbox-edit.md](references/sandbox-edit.md) |
+| `base44 sandbox grep <pattern>` | Search files by pattern in the remote sandbox | [sandbox-grep.md](references/sandbox-grep.md) |
+| `base44 sandbox run <command...>` | Run a shell command in the remote sandbox | [sandbox-run.md](references/sandbox-run.md) |
+| `base44 sandbox checkpoint` | Create a restore-point checkpoint of the sandbox | [sandbox-checkpoint.md](references/sandbox-checkpoint.md) |
+
 ### Script Execution
 
 Run one-off scripts against your app with the Base44 SDK pre-authenticated. Use it to perform CRUD operations on entities (`base44.entities.MyEntity.list/create/update/delete`), call backend functions (`base44.functions.invoke("myFunction", args)`), invoke agents, or access any other resource exposed by the SDK — without deploying a full function. Useful for data migrations, bulk operations, debugging, and scripted workflows.

diff --git a/skills/base44-cli/references/connectors-initiate.md b/skills/base44-cli/references/connectors-initiate.md
@@ -0,0 +1,64 @@
+# base44 connectors initiate
+
+Initialize a connector on an app and start its OAuth flow. Works without a local project — pass `--app-id` or set `BASE44_APP_ID`.
+
+## Syntax
+
+```bash
+npx base44 connectors initiate --integration-type <type> [--scopes <scopes...>]
+```
+
+## Options
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--integration-type <type>` | Integration type to initiate (e.g. `googlecalendar`, `gmail`, `slack`) | Yes |
+| `--scopes <scopes...>` | OAuth scopes to request (space- or comma-separated) | No |
+
+## What It Does
+
+1. Calls the Base44 API to initialize the connector for the given integration type
+2. If the connector is already authorized, reports that and exits (run `connectors pull` to fetch its config)
+3. Otherwise, opens a browser window for OAuth authorization (interactive mode) or prints the authorization URL (non-interactive / `--json` mode)
+4. In interactive mode, polls until authorization completes
+
+## Examples
+
+```bash
+# Initialize Google Calendar connector (no scopes — uses provider defaults)
+npx base44 connectors initiate --integration-type googlecalendar
+
+# Initialize Google Calendar with specific scopes
+npx base44 connectors initiate --integration-type googlecalendar --scopes https://www.googleapis.com/auth/calendar
+
+# Initialize Gmail with comma-separated scopes
+npx base44 connectors initiate --integration-type gmail --scopes scope.a,scope.b
+
+# Initialize against a specific app without a local project
+npx base44 connectors initiate --app-id app_123 --integration-type slack
+```
+
+## JSON Output
+
+Under `--json`, the command emits a machine-readable result and does not open a browser or poll. The caller is responsible for opening `redirectUrl` to complete authorization:
+
+```json
+{
+  "integrationType": "googlecalendar",
+  "alreadyAuthorized": false,
+  "redirectUrl": "https://auth.base44.io/oauth/...",
+  "connectionId": "conn_abc123"
+}
+```
+
+## Notes
+
+- Use `connectors initiate` when you need to authorize a single connector outside of the full `connectors push` flow
+- After authorization completes, run `npx base44 connectors pull` to fetch the connector config to local files
+- Scopes can be passed space-separated (`--scopes a b c`) or comma-joined (`--scopes a,b,c`) or mixed
+
+## Related Commands
+
+- [connectors-create.md](connectors-create.md) - How to create connector config files
+- [connectors-push.md](connectors-push.md) - Push all local connectors and authorize in one step
+- [connectors-pull.md](connectors-pull.md) - Pull connector configs to local files
diff --git a/skills/base44-cli/references/connectors-pull.md b/skills/base44-cli/references/connectors-pull.md
@@ -5,24 +5,30 @@ Pull connector configurations from Base44 to local files. Replaces all local con
 ## Syntax
 
 ```bash
-npx base44 connectors pull
+npx base44 connectors pull [options]
 ```
 
 ## Authentication
 
 **Required**: Yes. If not authenticated, you'll be prompted to login first.
 
+## Options
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--dir <path>` | Directory to write connector files to (default: `./connectors` when using `--app-id`) | No |
+
 ## What It Does
 
 1. Fetches all connectors from Base44
-2. Writes connector files to the `base44/connectors/` directory
+2. Writes connector files to the connectors directory
 3. Deletes local connector files that don't exist remotely
 4. Reports written and deleted connectors
 
 ## Prerequisites
 
-- Must be run from a Base44 project directory
-- Project must be linked to a Base44 app
+- Must be run from a linked Base44 project, OR pass `--app-id` / set `BASE44_APP_ID`
+- When using `--app-id`, connector files are written to `./connectors/` by default (override with `--dir`)
 
 ## Output
 
@@ -68,8 +74,9 @@ All connectors are already up to date
 
 ## Notes
 
-- Connector files are stored as `.jsonc` in the `base44/connectors/` directory
-- The directory location is configurable via `connectorsDir` in `config.jsonc`
+- Connector files are stored as `.jsonc`
+- For linked projects, the directory is `base44/connectors/` (configurable via `connectorsDir` in `config.jsonc`)
+- For projectless use (`--app-id`), defaults to `./connectors/` (override with `--dir`)
 - Use `base44 connectors push` to upload local changes to Base44
 
 ## Related Commands

diff --git a/skills/base44-cli/references/connectors-push.md b/skills/base44-cli/references/connectors-push.md
@@ -5,12 +5,18 @@ Push local connector configurations to Base44, synchronizing scopes and handling
 ## Usage
 
 ```bash
-npx base44 connectors push
+npx base44 connectors push [options]
 ```
 
+## Options
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--dir <path>` | Directory to read connector files from (default: `./connectors` when using `--app-id`) | No |
+
 ## What It Does
 
-1. **Reads local connectors** from your `base44/connectors/` directory
+1. **Reads local connectors** from your `base44/connectors/` directory (or `--dir` when using `--app-id`)
 2. **Syncs with Base44** - updates scopes for existing connectors
 3. **Adds new connectors** - new OAuth connector types trigger authorization; Stripe is provisioned automatically
 4. **Removes unlisted connectors** - connectors not in your local files are removed from Base44

diff --git a/skills/base44-cli/references/sandbox-checkpoint.md b/skills/base44-cli/references/sandbox-checkpoint.md
@@ -0,0 +1,44 @@
+# base44 sandbox checkpoint
+
+Create a restore-point checkpoint of an app's remote sandbox.
+
+## Syntax
+
+```bash
+npx base44 sandbox checkpoint [options]
+```
+
+## Options
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--name <name>` | Optional message/title for the checkpoint (defaults to an auto-generated title) | No |
+
+## Examples
+
+```bash
+# Create a checkpoint with an auto-generated title
+npx base44 sandbox checkpoint
+
+# Create a checkpoint with a descriptive name
+npx base44 sandbox checkpoint --name "before refactor"
+
+# Checkpoint against a specific app
+npx base44 sandbox checkpoint --app-id app_123 --name "pre-migration"
+```
+
+## Output
+
+Returns a JSON document with the checkpoint details (ID, name, timestamp).
+
+## Notes
+
+- Requires app context (`--app-id`, `BASE44_APP_ID`, or a linked project)
+- Use checkpoints before making risky edits (e.g., large refactors, schema migrations)
+- Checkpoints can be restored from the Base44 dashboard
+
+## Related Commands
+
+- [sandbox-run.md](sandbox-run.md) - Run commands in the sandbox
+- [sandbox-edit.md](sandbox-edit.md) - Edit files in the sandbox
+- [sandbox-write.md](sandbox-write.md) - Write files in the sandbox
diff --git a/skills/base44-cli/references/sandbox-edit.md b/skills/base44-cli/references/sandbox-edit.md
@@ -0,0 +1,71 @@
+# base44 sandbox edit
+
+Apply exact old→new string edits to a file in an app's remote sandbox.
+
+## Syntax
+
+```bash
+npx base44 sandbox edit <path> [options]
+# or pipe edits JSON via stdin
+echo '[{"old_text":"foo","new_text":"bar"}]' | npx base44 sandbox edit <path>
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<path>` | File path relative to the app root | Yes |
+
+## Options
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--edits-json <json>` | JSON array of edits (if omitted, read from stdin) | No |
+| `--dry-run` | Return the unified diff without writing | No |
+
+## Edit Format
+
+Each edit is a JSON object:
+
+```json
+{
+  "old_text": "exact string to find",
+  "new_text": "replacement string",
+  "replace_all": true
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `old_text` | string (non-empty) | Exact text to find in the file |
+| `new_text` | string | Replacement text (can be empty to delete) |
+| `replace_all` | boolean (optional) | Replace all occurrences (default: replace first only) |
+
+## Examples
+
+```bash
+# Single edit via flag
+npx base44 sandbox edit src/index.ts --edits-json '[{"old_text":"foo","new_text":"bar"}]'
+
+# Multiple edits via stdin
+echo '[{"old_text":"foo","new_text":"bar"},{"old_text":"baz","new_text":"qux"}]' \
+  | npx base44 sandbox edit src/index.ts
+
+# Preview without writing
+npx base44 sandbox edit src/index.ts --dry-run \
+  --edits-json '[{"old_text":"a","new_text":"b","replace_all":true}]'
+```
+
+## Notes
+
+- Requires app context (`--app-id`, `BASE44_APP_ID`, or a linked project)
+- All paths are relative to the app root
+- Edits are applied in order; each edit operates on the state after prior edits
+- Use `--dry-run` to verify edits before applying them
+- Returns JSON with the edit result (or diff when `--dry-run`)
+
+## Related Commands
+
+- [sandbox-read.md](sandbox-read.md) - Read file contents first to construct edits
+- [sandbox-write.md](sandbox-write.md) - Full file overwrite
+- [sandbox-grep.md](sandbox-grep.md) - Find patterns before editing
diff --git a/skills/base44-cli/references/sandbox-grep.md b/skills/base44-cli/references/sandbox-grep.md
@@ -0,0 +1,60 @@
+# base44 sandbox grep
+
+Search files for a pattern in an app's remote sandbox.
+
+## Syntax
+
+```bash
+npx base44 sandbox grep <pattern> [options]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<pattern>` | Search pattern (regex by default) | Yes |
+
+## Options
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--path <path>` | Subtree to search, relative to the app root | No |
+| `--no-regex` | Treat the pattern as a literal string, not a regex | No |
+| `--case-sensitive` | Case-sensitive match | No |
+| `--glob <glob>` | File glob filter (e.g. `"*.tsx"`) | No |
+| `--max-results <n>` | Maximum number of match lines to return | No |
+
+## Examples
+
+```bash
+# Search for a pattern across all files
+npx base44 sandbox grep "fetchUser"
+
+# Search only in src/
+npx base44 sandbox grep "fetchUser" --path src
+
+# Literal string search (no regex)
+npx base44 sandbox grep "user.email" --no-regex
+
+# Case-sensitive search in TypeScript files
+npx base44 sandbox grep "useState" --case-sensitive --glob "*.tsx"
+
+# Limit results
+npx base44 sandbox grep "TODO" --max-results 20
+```
+
+## Output
+
+Returns a JSON document with matching lines, their file paths, and line numbers.
+
+## Notes
+
+- Requires app context (`--app-id`, `BASE44_APP_ID`, or a linked project)
+- Patterns are treated as regular expressions by default; use `--no-regex` for literal matching
+- Search is case-insensitive by default; use `--case-sensitive` to match case exactly
+
+## Related Commands
+
+- [sandbox-read.md](sandbox-read.md) - Read a specific file after finding it
+- [sandbox-edit.md](sandbox-edit.md) - Edit a file after locating the target text
+- [sandbox-ls.md](sandbox-ls.md) - List directory structure