Update base44-cli skill to v0.1.1 June 29, 2026 06:24 UTC

CLI_VERSION

@@ -1 +1 @@
-v0.0.56
+v0.1.1

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.1
 ---
 
 # Base44 CLI
@@ -192,6 +192,29 @@ npx base44 <command>
 
 **Note:** All commands in this documentation use `npx base44`. You can also use `yarn base44`, or `pnpm base44` if preferred.
 
+## Global `--json` Option
+
+The CLI has a global `--json` flag that switches all commands to machine-readable mode:
+
+- **stdout** contains a single JSON document (the command's data output)
+- **Human-oriented status messages, spinners, and logs** go to stderr (stdout stays clean)
+- **Forces non-interactive mode**: prompts and OAuth browser flows are skipped
+
+Use `--json` when you need to parse or pipe command output programmatically:
+
+```bash
+# Get connector list as JSON
+npx base44 connectors list-available --json | jq '.integrations[].integrationType'
+
+# Get logs as JSON
+npx base44 logs --json | jq '.[] | select(.level == "error")'
+
+# Initiate a connector and extract the redirect URL
+npx base44 connectors initiate --app-id app_123 --integration-type googlecalendar --json | jq -r '.redirectUrl'
+```
+
+Commands that do not produce data output (e.g. `deploy`) still return `{ "output": "<status>" }` so stdout is always valid JSON.
+
 ## Global `--app-id` Option
 
 The CLI has a global `--app-id <id>` option for commands that only need an app context, not local project files.
@@ -345,6 +368,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`       | Initialize a connector and start its OAuth flow (works without a local project) | [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)                 |
 
@@ -416,6 +440,20 @@ Run one-off scripts against your app with the Base44 SDK pre-authenticated. Use
 
 **No authentication required.** Runs entirely locally. Automatically updates `tsconfig.json` to include the generated types.
 
+### Remote Sandbox Development
+
+Interact with an app's server-side sandbox — read, write, edit, search, and run commands remotely. All sandbox commands work from a linked project directory or with `--app-id` / `BASE44_APP_ID`.
+
+| Command | Description | Reference |
+|---------|-------------|-----------|
+| `base44 sandbox ls [path]` | List directory entries in an app's remote sandbox | [sandbox-list-directory.md](references/sandbox-list-directory.md) |
+| `base44 sandbox read <paths...>` | Read file contents from an app's remote sandbox | [sandbox-read-file.md](references/sandbox-read-file.md) |
+| `base44 sandbox write <path>` | Create or overwrite a file in an app's remote sandbox | [sandbox-write-file.md](references/sandbox-write-file.md) |
+| `base44 sandbox edit <path>` | Apply exact old→new string edits to a file in the sandbox | [sandbox-edit-file.md](references/sandbox-edit-file.md) |
+| `base44 sandbox grep <pattern>` | Search files for a pattern in an app's remote sandbox | [sandbox-grep.md](references/sandbox-grep.md) |
+| `base44 sandbox run <command...>` | Run a shell command in an app's remote sandbox | [sandbox-run-command.md](references/sandbox-run-command.md) |
+| `base44 sandbox checkpoint` | Create a restore-point checkpoint of an app's remote sandbox | [sandbox-checkpoint.md](references/sandbox-checkpoint.md) |
+
 ### Site Management
 
 | Command              | Description                               | Reference                                   |

skills/base44-cli/references/connectors-initiate.md

@@ -0,0 +1,63 @@
+# base44 connectors initiate
+
+Initialize a connector on an app and start its OAuth flow. Works without a local project directory when `--app-id` is provided.
+
+## Syntax
+
+```bash
+npx base44 connectors initiate --integration-type <type> [options]
+```
+
+## 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 |
+
+## Examples
+
+```bash
+# Initiate Google Calendar connector on a specific app (no local project needed)
+npx base44 connectors initiate --app-id app_123 --integration-type googlecalendar
+
+# With specific OAuth scopes (space-separated)
+npx base44 connectors initiate --integration-type googlecalendar --scopes https://www.googleapis.com/auth/calendar
+
+# Multiple scopes, comma-separated
+npx base44 connectors initiate --integration-type gmail --scopes scope.a,scope.b
+```
+
+## Behavior
+
+1. Sends an initiate request to Base44 for the specified integration type
+2. If the connector is already authorized, reports so and suggests running `connectors pull`
+3. If authorization is needed, provides a redirect URL for the OAuth flow:
+   - **Interactive mode**: Logs the URL, opens the browser, and polls until authorized
+   - **Non-interactive mode** (no TTY / `--app-id` only): Prints the URL and returns — open it manually to authorize
+   - **JSON mode** (`--json`): Returns the URL in structured output without opening a browser
+
+## JSON Mode Output (`--json`)
+
+```json
+{
+  "integrationType": "googlecalendar",
+  "alreadyAuthorized": false,
+  "redirectUrl": "https://auth.base44.io/oauth/...",
+  "connectionId": "conn_123"
+}
+```
+
+After opening the redirect URL and completing the OAuth flow, run `npx base44 connectors pull` to fetch the connector config.
+
+## Notes
+
+- Does not require a local project directory — can be used with `--app-id` or `BASE44_APP_ID`
+- Run `npx base44 connectors list-available` to see all supported integration types
+- After successful authorization, run `npx base44 connectors pull` to sync config locally
+
+## Related Commands
+
+- [connectors-list-available.md](connectors-list-available.md) - List all available integration types
+- [connectors-pull.md](connectors-pull.md) - Pull connectors from Base44 to local files
+- [connectors-push.md](connectors-push.md) - Push local connectors to Base44

skills/base44-cli/references/connectors-pull.md

@@ -5,24 +5,31 @@ Pull connector configurations from Base44 to local files. Replaces all local con
 ## Syntax
 
 ```bash
-npx base44 connectors pull
+npx base44 connectors pull [options]
 ```
 
+## Options
+
+| Option | Description | Required |
+|--------|-------------|----------|
+| `--dir <path>` | Directory to write connector files to (default: `./connectors` when using `--app-id`) | No |
+
 ## Authentication
 
 **Required**: Yes. If not authenticated, you'll be prompted to login first.
 
 ## What It Does
 
 1. Fetches all connectors from Base44
-2. Writes connector files to the `base44/connectors/` directory
+2. Writes connector files to the project's connectors directory
 3. Deletes local connector files that don't exist remotely
 4. Reports written and deleted connectors
 
-## Prerequisites
+## App Context
 
-- Must be run from a Base44 project directory
-- Project must be linked to a Base44 app
+Works in two modes:
+- **Linked project** (default): reads the connectors directory from `base44/config.jsonc`
+- **App ID mode** (`--app-id` or `BASE44_APP_ID`): no local project required; writes to `./connectors` by default (override with `--dir`)
 
 ## Output
 
@@ -68,8 +75,8 @@ 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` in the connectors directory
+- When using a linked project, the directory location is configurable via `connectorsDir` in `config.jsonc`
 - Use `base44 connectors push` to upload local changes to Base44
 
 ## Related Commands

skills/base44-cli/references/connectors-push.md

@@ -5,9 +5,21 @@ 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 |
+
+## App Context
+
+Works in two modes:
+- **Linked project** (default): reads connectors from the project's connectors directory (configured via `connectorsDir` in `config.jsonc`)
+- **App ID mode** (`--app-id` or `BASE44_APP_ID`): no local project required; reads from `./connectors` by default (override with `--dir`)
+
 ## What It Does
 
 1. **Reads local connectors** from your `base44/connectors/` directory

skills/base44-cli/references/sandbox-checkpoint.md

@@ -0,0 +1,43 @@
+# 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 custom name
+npx base44 sandbox checkpoint --name "before refactor"
+
+# On a specific app (no local project needed)
+npx base44 sandbox checkpoint --app-id app_123 --name "stable state"
+```
+
+## JSON Output
+
+The command always returns JSON to stdout describing the created checkpoint.
+
+## Notes
+
+- Works from a linked project directory or with `--app-id` / `BASE44_APP_ID`
+- Use checkpoints before large edits so you can restore to a known-good state
+
+## Related Commands
+
+- [sandbox-read-file.md](sandbox-read-file.md) - Read files from the sandbox
+- [sandbox-write-file.md](sandbox-write-file.md) - Write files to the sandbox
+- [sandbox-edit-file.md](sandbox-edit-file.md) - Edit files in the sandbox

skills/base44-cli/references/sandbox-edit-file.md

@@ -0,0 +1,63 @@
+# 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]
+```
+
+## 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, reads from stdin | No |
+| `--dry-run` | Return the unified diff without writing the file | No |
+
+## Edit Format
+
+Each edit is a JSON object:
+```json
+{ "old_text": "...", "new_text": "...", "replace_all": true }
+```
+
+- `old_text` — exact string to find (must be non-empty)
+- `new_text` — replacement string (can be empty to delete)
+- `replace_all` — optional boolean; if `true`, replaces all occurrences (default: first only)
+
+Pass as an array: `[{ "old_text": "foo", "new_text": "bar" }]`
+
+## Examples
+
+```bash
+# Edit via piped stdin
+echo '[{"old_text":"foo","new_text":"bar"}]' | npx base44 sandbox edit src/x.ts
+
+# Edit via flag
+npx base44 sandbox edit src/x.ts --edits-json '[{"old_text":"a","new_text":"b","replace_all":true}]'
+
+# Dry run — see the diff without writing
+npx base44 sandbox edit src/x.ts --dry-run --edits-json '[{"old_text":"a","new_text":"b"}]'
+```
+
+## JSON Output
+
+Returns a JSON object describing the applied edits or (with `--dry-run`) the unified diff.
+
+## Notes
+
+- Works from a linked project directory or with `--app-id` / `BASE44_APP_ID`
+- If `--edits-json` is omitted and nothing is piped, the command throws an error
+
+## Related Commands
+
+- [sandbox-read-file.md](sandbox-read-file.md) - Read file contents from the sandbox
+- [sandbox-write-file.md](sandbox-write-file.md) - Create or overwrite a file in the sandbox
+- [sandbox-grep.md](sandbox-grep.md) - Search files in the sandbox

skills/base44-cli/references/sandbox-grep.md

@@ -0,0 +1,59 @@
+# 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 (default: case-insensitive) | 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 in all files
+npx base44 sandbox grep "TODO"
+
+# Literal string search (not regex)
+npx base44 sandbox grep "console.log(" --no-regex
+
+# Search only TypeScript files
+npx base44 sandbox grep "useState" --glob "*.tsx"
+
+# Case-sensitive search in a specific directory
+npx base44 sandbox grep "MyComponent" --path src/components --case-sensitive
+
+# Limit to 20 results
+npx base44 sandbox grep "import" --max-results 20
+```
+
+## JSON Output
+
+Returns a JSON object with match lines, file paths, and line numbers.
+
+## Notes
+
+- Works from a linked project directory or with `--app-id` / `BASE44_APP_ID`
+- Pattern is treated as a regex by default; use `--no-regex` for literal searches
+
+## Related Commands
+
+- [sandbox-read-file.md](sandbox-read-file.md) - Read a specific file's contents
+- [sandbox-list-directory.md](sandbox-list-directory.md) - List directory entries
+- [sandbox-edit-file.md](sandbox-edit-file.md) - Edit files in the sandbox