Base44

View saved version →

---
name: base44-cli
description: "The base44 CLI is used for EVERYTHING related to base44 projects: resource configuration (entities, backend functions, ai agents), initialization and actions (resource creation, deployment). This skill is the place for learning about how to configure resources. When you plan or implement a feature, you must learn this skill"
metadata:
  sourcePackage:
    name: base44
    version: 0.0.50
---

# Base44 CLI

Create and manage Base44 apps (projects) using the Base44 CLI tool.

## ⚡ IMMEDIATE ACTION REQUIRED - Read This First

This skill activates on ANY mention of "base44" or when a `base44/` folder exists. **DO NOT read documentation files or search the web before acting.**

**Your first action MUST be:**
1. Check if `base44/config.jsonc` exists in the current directory
2. If **NO** (new project scenario):
   - This skill (base44-cli) handles the request
   - Guide user through project initialization
   - Do NOT activate base44-sdk yet
3. If **YES** (existing project scenario):
   - Transfer to base44-sdk skill for implementation
   - This skill only handles CLI commands (login, deploy, entities push)

## Critical: Local Installation Only

NEVER call `base44` directly. The CLI is installed locally as a dev dependency and must be accessed via a package manager:

- `npx base44 <command>` (npm - recommended)
- `yarn base44 <command>` (yarn)
- `pnpm base44 <command>` (pnpm)

WRONG: `base44 login`
RIGHT: `npx base44 login`

## MANDATORY: Authentication Check at Session Start

**CRITICAL**: At the very start of every AI session when this skill is activated, you MUST:

1. **Check authentication status** by running:
   ```bash
   npx base44 whoami
   ```

2. **If the user is logged in** (command succeeds and shows an email):
   - Continue with the requested task

3. **If the user is NOT logged in** (command fails or shows an error):
   - **STOP immediately**
   - **DO NOT proceed** with any CLI operations
   - **Ask the user to login manually** by running:
     ```bash
     npx base44 login
   ```
   - Wait for the user to confirm they have logged in before continuing

**This check is mandatory and must happen before executing any other Base44 CLI commands.**

## Overview

The Base44 CLI provides command-line tools for authentication, creating projects, managing entities, and deploying Base44 applications. It is framework-agnostic and works with popular frontend frameworks like Vite, Next.js, and Create React App, Svelte, Vue, and more.

## When to Use This Skill vs base44-sdk

**Use base44-cli when:**
- Creating a **NEW** Base44 project from scratch
- Initializing a project in an empty directory
- Directory is missing `base44/config.jsonc`
- User mentions: "create a new project", "initialize project", "setup a project", "start a new Base44 app"
- Deploying, pushing entities, or authenticating via CLI
- Working with CLI commands (`npx base44 ...`)

**Use base44-sdk when:**
- Building features in an **EXISTING** Base44 project
- `base44/config.jsonc` already exists
- Writing JavaScript/TypeScript code using Base44 SDK
- Implementing functionality, components, or features
- User mentions: "implement", "build a feature", "add functionality", "write code"

**Skill Dependencies:**
- `base44-cli` is a **prerequisite** for `base44-sdk` in new projects
- If user wants to "create an app" and no Base44 project exists, use `base44-cli` first
- `base44-sdk` assumes a Base44 project is already initialized

**State Check Logic:**
Before selecting a skill, check:
- IF (user mentions "create/build app" OR "make a project"):
  - IF (directory is empty OR no `base44/config.jsonc` exists):
    → Use **base44-cli** (project initialization needed)
  - ELSE:
    → Use **base44-sdk** (project exists, build features)

## Project Structure

A Base44 project combines a standard frontend project with a `base44/` configuration folder:

```
my-app/
├── base44/                      # Base44 configuration (created by CLI)
│   ├── config.jsonc             # Project settings, site config
│   ├── .types/                  # Auto-generated TypeScript types (created by `types generate`)
│   │   └── types.d.ts           # Module augmentation for @base44/sdk
│   ├── entities/                # Entity schema definitions
│   │   ├── task.jsonc
│   │   └── board.jsonc
│   ├── functions/               # Backend functions (optional); automations live in function.jsonc
│   │   └── my-function/
│   │       ├── function.jsonc
│   │       └── index.ts
│   ├── agents/                  # Agent configurations (optional)
│   │   └── support_agent.jsonc
│   └── connectors/              # OAuth connector configurations (optional)
│       └── googlecalendar.jsonc
├── src/                         # Frontend source code
│   ├── api/
│   │   └── base44Client.js      # Base44 SDK client
│   ├── pages/
│   ├── components/
│   └── main.jsx
├── index.html                   # SPA entry point
├── package.json
└── vite.config.js               # Or your framework's config
```

**Key files:**
- `base44/config.jsonc` - Project name, description, site build settings
- `base44/entities/*.jsonc` - Data model schemas (see Entity Schema section)
- `base44/functions/*/function.jsonc` - Function config and optional `automations` (CRON, simple triggers, entity hooks)
- `base44/agents/*.jsonc` - Agent configurations (optional)
- `base44/.types/types.d.ts` - Auto-generated TypeScript types for entities, functions, and agents (created by `npx base44 types generate`)
- `base44/connectors/*.jsonc` - OAuth connector configurations (optional)
- `src/api/base44Client.js` - Pre-configured SDK client for frontend use

**config.jsonc example:**
```jsonc
{
  "name": "My App",                    // Required: project name
  "description": "App description",    // Optional: project description
  "entitiesDir": "./entities",         // Optional: default "entities"
  "functionsDir": "./functions",       // Optional: default "functions"
  "agentsDir": "./agents",             // Optional: default "agents"
  "connectorsDir": "./connectors",     // Optional: default "connectors"
  "site": {                            // Optional: site deployment config
    "installCommand": "npm install",   // Optional: install dependencies
    "buildCommand": "npm run build",   // Optional: build command
    "serveCommand": "npm run dev",     // Optional: local dev server
    "outputDirectory": "./dist"        // Optional: build output directory
  }
}
```

**Config properties:**

| Property | Description | Default |
|----------|-------------|---------|
| `name` | Project name (required) | - |
| `description` | Project description | - |
| `entitiesDir` | Directory for entity schemas | `"entities"` |
| `functionsDir` | Directory for backend functions | `"functions"` |
| `agentsDir` | Directory for agent configs | `"agents"` |
| `connectorsDir` | Directory for connector configs | `"connectors"` |
| `site.installCommand` | Command to install dependencies | - |
| `site.buildCommand` | Command to build the project | - |
| `site.serveCommand` | Command to run dev server | - |
| `site.outputDirectory` | Build output directory for deployment | - |

## Installation

Install the Base44 CLI as a dev dependency in your project:

```bash
npm install --save-dev base44
```

**Important:** Never assume or hardcode the `base44` package version. Always install without a version specifier to get the latest version.

Then run commands using `npx`:

```bash
npx base44 <command>
```

**Note:** All commands in this documentation use `npx base44`. You can also use `yarn base44`, or `pnpm base44` if preferred.

## Available Commands

### Authentication

| Command         | Description                                     | Reference                                   |
| --------------- | ----------------------------------------------- | ------------------------------------------- |
| `base44 login`  | Authenticate with Base44 using device code flow | [auth-login.md](references/auth-login.md)   |
| `base44 logout` | Logout from current device                      | [auth-logout.md](references/auth-logout.md) |
| `base44 whoami` | Display current authenticated user              | [auth-whoami.md](references/auth-whoami.md) |

### Project Management

| Command | Description | Reference |
|---------|-------------|-----------|
| `base44 create` | Create a new Base44 project from a template | [create.md](references/create.md) ⚠️ **MUST READ** |
| `base44 link` | Link an existing local project to Base44 | [link.md](references/link.md) |
| `base44 eject` | Download the code for an existing Base44 project | [eject.md](references/eject.md) |
| `base44 dashboard open` | Open the app dashboard in your browser | [dashboard.md](references/dashboard.md) |

### Deployment

| Command | Description | Reference |
|---------|-------------|-----------|
| `base44 deploy` | Deploy all resources (entities, functions, agents, connectors, auth config, and site) | [deploy.md](references/deploy.md) |

### Entity Management

| Action / Command       | Description                                 | Reference                                           |
| ---------------------- | ------------------------------------------- | --------------------------------------------------- |
| Create Entities        | Define entities in `base44/entities` folder | [entities-create.md](references/entities-create.md) |
| `base44 entities push` | Push local entities to Base44               | [entities-push.md](references/entities-push.md)     |
| RLS Patterns           | Row-level security examples and operators   | [rls-examples.md](references/rls-examples.md) ⚠️ **READ FOR RLS** |

#### Entity Schema (Quick Reference)

ALWAYS follow this exact structure when creating entity files:

**File naming:** `base44/entities/{kebab-case-name}.jsonc` (e.g., `team-member.jsonc` for `TeamMember`)

**Schema template:**
```jsonc
{
  "name": "EntityName",
  "type": "object",
  "properties": {
    "field_name": {
      "type": "string",
      "description": "Field description"
    }
  },
  "required": ["field_name"]
}
```

**Field types:** `string`, `number`, `integer`, `boolean`, `array`, `object`, `binary`
**String formats:** `date`, `date-time`, `time`, `email`, `uri`, `hostname`, `ipv4`, `ipv6`, `uuid`, `file`, `regex`, `richtext`
**For enums:** Add `"enum": ["value1", "value2"]` and optionally `"default": "value1"`
**Entity names:** Must be alphanumeric only (pattern: `/^[a-zA-Z0-9]+$/`)

For complete documentation, see [entities-create.md](references/entities-create.md).

### Function Management

| Action / Command          | Description                                   | Reference                                               |
| ------------------------- | --------------------------------------------- | ------------------------------------------------------- |
| Create Functions          | Define functions in `base44/functions` folder | [functions-create.md](references/functions-create.md)   |
| Configure Automations     | CRON, simple triggers, entity hooks in `function.jsonc` | [automations.md](references/automations.md)   |
| `base44 functions deploy [names...] [--force]` | Deploy local functions (and automations) to Base44; optionally target specific functions or prune removed ones | [functions-deploy.md](references/functions-deploy.md)   |
| `base44 functions delete <names...>` | Delete one or more deployed functions from Base44 | [functions-delete.md](references/functions-delete.md) |
| `base44 functions list`   | List all deployed functions on Base44 remote  | [functions-list.md](references/functions-list.md)       |
| `base44 functions pull [name]` | Pull deployed functions from Base44 to local files | [functions-pull.md](references/functions-pull.md)  |

### Agent Management

Agents are conversational AI assistants that can interact with users, access your app's entities, and call backend functions. Use these commands to manage agent configurations.

| Action / Command        | Description                             | Reference                                       |
| ----------------------- | --------------------------------------- | ----------------------------------------------- |
| Create Agents           | Define agents in `base44/agents` folder | See Agent Schema below                          |
| `base44 agents pull`    | Pull remote agents to local files       | [agents-pull.md](references/agents-pull.md)     |
| `base44 agents push`    | Push local agents to Base44             | [agents-push.md](references/agents-push.md)     |

**Note:** Agent commands perform full synchronization - pushing replaces all remote agents with local ones, and pulling replaces all local agents with remote ones.

#### Agent Schema (Quick Reference)

**File naming:** `base44/agents/{agent_name}.jsonc` (e.g., `support_agent.jsonc`)

**Schema template:**
```jsonc
{
  "name": "agent_name",
  "description": "Brief description of what this agent does",
  "instructions": "Detailed instructions for the agent's behavior",
  "tool_configs": [
    // Entity tool - gives agent access to entity operations
    { "entity_name": "tasks", "allowed_operations": ["read", "create", "update", "delete"] },
    // Backend function tool - gives agent access to a function
    { "function_name": "send_email", "description": "Send an email notification" }
  ],
  "whatsapp_greeting": "Hello! How can I help you today?"
}
```

**Naming rules:** 
- Agent names must match pattern: `/^[a-z0-9_]+$/` (lowercase alphanumeric with underscores, 1-100 chars)
- Valid: `support_agent`, `order_bot`
- Invalid: `Support-Agent`, `OrderBot`

**Required fields:** `name`, `description`, `instructions`
**Optional fields:** `tool_configs` (defaults to `[]`), `whatsapp_greeting`

**Tool config types:**
- **Entity tools**: `entity_name` + `allowed_operations` (array of: `read`, `create`, `update`, `delete`)
- **Backend function tools**: `function_name` + `description`

### Connector Management

Connectors let your app connect to external services (Google Calendar, Slack, Stripe, etc.). Most connectors use OAuth to provide access tokens for backend functions to call external APIs. Stripe is the exception — it is provisioned automatically on the server side with no OAuth browser flow.

| Action / Command                   | Description                                          | Reference                                                           |
| ---------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| 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 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)                 |

**Note:** Connector commands perform full synchronization - pushing replaces all remote connectors with local ones (and triggers OAuth for new OAuth connectors), and pulling replaces all local connectors with remote ones.

#### Connector Schema (Quick Reference)

**File naming:** `base44/connectors/{type}.jsonc` (e.g., `googlecalendar.jsonc`, `slack.jsonc`)

**Schema template:**
```jsonc
{
  "type": "googlecalendar",
  "scopes": [
    "https://www.googleapis.com/auth/calendar.readonly",
    "https://www.googleapis.com/auth/calendar.events"
  ]
}
```

**Required fields:** `type`
**Optional fields:** `scopes` (defaults to `[]`)

**Available connector types:** Run `npx base44 connectors list-available` to see all supported integration types.

**Note:** `stripe` is also a valid connector type but is not returned by `list-available`. Treat it as a supported type — it is provisioned automatically by Base44 with no OAuth browser flow. See [connectors-create.md](references/connectors-create.md) for details.

For complete documentation, see [connectors-create.md](references/connectors-create.md).

#### Automation Quick Reference

Automations are triggers defined in the `automations` array inside `function.jsonc`. They deploy with the function via `base44 functions deploy`. Four types:

**Common fields (all types):** `name` (required), `description`, `function_args`, `is_active` (default: true)

**Scheduled One-Time:** `type: "scheduled"`, `schedule_mode: "one-time"`, `one_time_date` (ISO string)

**Scheduled CRON:** `type: "scheduled"`, `schedule_mode: "recurring"`, `schedule_type: "cron"`, `cron_expression`, optional `ends_type` / `ends_on_date` / `ends_after_count`

**Scheduled Simple:** `type: "scheduled"`, `schedule_mode: "recurring"`, `schedule_type: "simple"`, `repeat_unit` (`"minutes"` \| `"hours"` \| `"days"` \| `"weeks"` \| `"months"`), optional `repeat_interval`, `start_time`, `repeat_on_days` (0–6), `repeat_on_day_of_month` (1–31), `ends_type` / `ends_on_date` / `ends_after_count`

**Entity Hook:** `type: "entity"`, `entity_name` (matches entity schema name), `event_types`: array of `"create"` \| `"update"` \| `"delete"` (at least one)

For full schemas and examples, see [automations.md](references/automations.md).

### Auth Configuration

Manage your app's authentication settings (e.g., username & password login). Auth config is stored in `base44/auth/` and synced with Base44 via `auth push`/`auth pull`.

| Command | Description | Reference |
|---------|-------------|-----------|
| `base44 auth password-login <enable\|disable>` | Enable or disable username & password authentication | [auth-password-login.md](references/auth-password-login.md) |
| `base44 auth pull` | Pull auth config from Base44 to local files | [auth-pull.md](references/auth-pull.md) |
| `base44 auth push` | Push local auth config to Base44 | [auth-push.md](references/auth-push.md) |

**Note:** Auth config is also deployed as part of `base44 deploy`.

### Secrets Management

Manage project secrets (environment variables stored securely in Base44). These commands are hidden from `--help` output but are fully functional.

| Command | Description | Reference |
|---------|-------------|-----------|
| `base44 secrets list` | List the names of all secrets | [secrets-list.md](references/secrets-list.md) |
| `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) |

### 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 automation scripts.

| Command | Description | Reference |
|---------|-------------|-----------|
| `base44 exec` | Run a script (via stdin) with the Base44 SDK pre-authenticated | [exec.md](references/exec.md) |

### Type Generation

| Command | Description | Reference |
|---------|-------------|-----------|
| `base44 types generate` | Generate TypeScript types (`types.d.ts`) from entities, functions, agents, and connectors | [types-generate.md](references/types-generate.md) |

**Output:** `base44/.types/types.d.ts` — augments `@base44/sdk` module with typed registries (`EntityTypeRegistry`, `FunctionNameRegistry`, `AgentNameRegistry`, `ConnectorTypeRegistry`).

**No authentication required.** Runs entirely locally. Automatically updates `tsconfig.json` to include the generated types.

### 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)     |

**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).

## Quick Start

1. Install the CLI in your project:
   ```bash
   npm install --save-dev base44
   ```

2. Authenticate with Base44:
   ```bash
   npx base44 login
   ```

3. Create a new project (ALWAYS provide name and `--path` flag):
   ```bash
   npx base44 create my-app -p .
   ```

4. Build and deploy everything:
   ```bash
   npm run build
   npx base44 deploy -y
   ```

Or deploy individual resources:
- `npx base44 entities push` - Push entities only
- `npx base44 functions deploy` - Deploy functions only
- `npx base44 functions delete <name>` - Delete a deployed function
- `npx base44 functions list` - List all deployed functions
- `npx base44 functions pull` - Pull deployed functions to local files
- `npx base44 agents push` - Push agents only
- `npx base44 connectors pull` - Pull connectors from Base44
- `npx base44 connectors push` - Push connectors only
- `npx base44 auth pull` - Pull auth config from Base44
- `npx base44 auth push` - Push auth config only
- `npx base44 site deploy -y` - Deploy site only

## Common Workflows

### Creating a New Project

**⚠️ MANDATORY: Before running `base44 create`, you MUST read [create.md](references/create.md) for:**
- **Template selection** - Choose the correct template (`backend-and-client` vs `backend-only`)
- **Correct workflow** - Different templates require different setup steps
- **Common pitfalls** - Avoid folder creation errors that cause failures

Failure to follow the create.md instructions will result in broken project scaffolding.

### Linking an Existing Project
```bash
# If you have base44/config.jsonc but no .app.jsonc
npx base44 link --create --name my-app
```

### Deploying All Changes
```bash
# Generate types (optional, for TypeScript projects)
npx base44 types generate

# Build your project first
npm run build

# Deploy everything (entities, functions, and site)
npx base44 deploy -y
```

### Generating TypeScript Types
```bash
# Generate types from entities, functions, agents, and connectors
npx base44 types generate
```

This creates `base44/.types/types.d.ts` with typed registries for the `@base44/sdk` module. Run this after changing entities, functions, agents, or connectors to keep your types in sync. No authentication required.

### Deploying Individual Resources
```bash
# Push only entities
npx base44 entities push

# Deploy only functions (all)
npx base44 functions deploy
# Deploy specific functions
npx base44 functions deploy my-function other-function
# Deploy and prune removed functions
npx base44 functions deploy --force

# Push only agents
npx base44 agents push

# Pull connectors from Base44
npx base44 connectors pull

# Push only connectors
npx base44 connectors push

# Deploy only site
npx base44 site deploy -y
```

### Opening the Dashboard
```bash
# Open app dashboard in browser
npx base44 dashboard
```

## Authentication

Most commands require authentication. If you're not logged in, the CLI will automatically prompt you to login. Your session is stored locally and persists across CLI sessions.

## Troubleshooting

| Error                       | Solution                                                                            |
| --------------------------- | ----------------------------------------------------------------------------------- |
| Not authenticated           | Run `npx base44 login` first                                                        |
| No entities found           | Ensure entities exist in `base44/entities/` directory                               |
| Entity not recognized       | Ensure file uses kebab-case naming (e.g., `team-member.jsonc` not `TeamMember.jsonc`) |
| No functions found          | Ensure functions exist in `base44/functions/` with valid `function.jsonc` configs   |
| No agents found             | Ensure agents exist in `base44/agents/` directory with valid `.jsonc` configs       |
| Invalid agent name          | Agent names must be lowercase alphanumeric with underscores only                    |
| No connectors found         | Ensure connectors exist in `base44/connectors/` directory with valid `.jsonc` configs |
| Invalid connector type      | Run `npx base44 connectors list-available` to see valid types |
| Duplicate connector type    | Each connector type can only be defined once per project                            |
| Connector authorization timeout | Re-run `npx base44 connectors push` and complete the OAuth flow in your browser  |
| No site configuration found | Check that `site.outputDirectory` is configured in project config                   |
| Site deployment fails       | Ensure you ran `npm run build` first and the build succeeded                        |
| Update available message    | If prompted to update, run `npm install -g base44@latest` (or use npx for local installs) |

Referenced files: 34

View saved version →

---
name: base44-remote-dev
description: >-
  Develop a Base44 app remotely from your own coding agent (Claude Code,
  claude.ai, or any MCP client) by connecting it to the Base44 sandbox. Cloud
  agents connect over MCP; local agents can connect over MCP or drive the same
  sandbox with the `base44 sandbox` CLI subcommands (the CLI uses shorter
  names — e.g. read_file is `sandbox read`, list_directory is `sandbox ls`,
  run_command is `sandbox run`). Covers connecting/
  authenticating, the available sandbox tools (run_command, read_file,
  write_file, edit_file, grep, list_directory, create_checkpoint,
  get_app_preview_url, get_app_status, list_user_apps, and the connector tools
  list_connectors / initiate_connector_connection), the edit→preview→verify loop, how changes
  persist, builder/external-agent concurrency, the in-editor "Send to Coding
  Agent" button + onboarding README URLs, and tips like reading the Vite
  dev-server logs. Triggers on "develop my Base44 app remotely", "connect
  Claude Code to Base44", "bring my own agent", "edit a Base44 app over MCP",
  "Base44 sandbox MCP", or "Send to Coding Agent".
---

<!--
  Vendored from base44-dev/apper PR #11608
  (docs/features/bring-your-own-model/base44-remote-dev/SKILL.md).
  Keep in sync with the upstream source if it changes.
-->

# Remotely develop a Base44 app over MCP

Connect your own coding agent to a Base44 app's sandbox and develop in it
directly — run commands, read and edit files, grep, list directories — while
Base44 supplies the sandbox and you supply the agent and the LLM.

This works with any MCP-capable client. The examples use Claude Code.

> **Easiest start:** in the Base44 app editor, click **Send to Coding Agent**. For a local agent
> it gives you a ready-to-paste prompt (which fetches a README and drives the sandbox over MCP or
> the `base44 sandbox` CLI — Section 10);
> for the web it gives a prompt to paste into a **claude.ai** chat (with the Base44 MCP connector)
> plus an **Open Claude** button. The button is the discovery surface — the rest of this skill is
> the reference.

> **Two transports:** web agents use **claude.ai** with the Base44 **MCP connector** (Sections
> 1–9) — note this is the regular claude.ai chat, *not* Claude Code on the web (`claude.ai/code`),
> which runs in its own repo-backed sandbox. A local agent can connect that same MCP server, or
> drive the sandbox with the **`base44 sandbox` CLI** (a Base44 CLI token, Section 10) — same tools,
> same behavior, same error codes; the CLI just exposes them under shorter command names
> (`sandbox read`, `sandbox ls`, …).

---

## 1. Connect the MCP server

The Base44 MCP endpoint is:

```
https://app.base44.com/mcp
```

Register it with Claude Code (run from any folder):

```bash
claude mcp add --transport http base44 https://app.base44.com/mcp
```

Add `--scope user` if you want it available in every project rather than just
the current folder.

`claude mcp add` only writes the config — it does not authenticate yet.

## 2. Authenticate

Start Claude Code and open the MCP menu:

```bash
claude
```

then, inside Claude Code:

```
/mcp
```

Select **base44** → **Authenticate**. A browser opens for the Base44 OAuth
flow (PKCE) — log in and approve. When it succeeds, `/mcp` shows **base44** as
connected and lists its tools.

**Pure-CLI / headless clients** that can't open a browser use the OAuth device
flow (`/oauth/device/code`) instead — request a code, approve it in a browser
on another device, and the client receives the token.

### Scopes

| Tools | Required scope |
|---|---|
| `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (granted by default) |
| `write_file`, `edit_file`, `run_command`, `create_checkpoint` | `sandbox:write` |

`sandbox:write` is **not** granted by default — shell and file mutation
require it explicitly. If the read tools work but the mutating ones return
`NOT_AUTHORIZED`, your token is missing `sandbox:write`; reconnect and grant
sandbox access (the device flow can request it explicitly).

---

## 3. Pick the app and orient yourself

Every tool takes a required `appId`. Find your apps with `list_user_apps`, then
pin the id in your requests so the agent passes it on every call.

Start **read-only** to build a mental model before changing anything:

```
Using the base44 tools on appId <APP_ID>:
1. list_directory on the app root (recursive, depth 2)
2. read_file src/App.jsx and src/pages.config.js
3. grep for the component I want to change
Summarize the structure before editing.
```

> **Cold start:** if the app has no running sandbox, the first tool call
> transparently brings one up from your last commit — it just takes a bit
> longer. Subsequent calls are fast.

> **CLI names:** over the `base44 sandbox` CLI (Section 10) these read tools are
> `list_directory` → `sandbox ls`, `read_file` → `sandbox read`, and
> `grep` → `sandbox grep`.

---

## 4. Make changes

- **`edit_file`** (`sandbox edit` in the CLI) — preferred for changing existing files. Provide exact
  `old_text`→`new_text` edits. Each `old_text` must be unique in the file
  unless you set `replace_all`. All edits in a call apply atomically
  (all-or-nothing) and you get a unified diff back. Pass `dry_run: true` to
  preview the diff without writing.
- **`write_file`** (`sandbox write` in the CLI) — for creating new files. To overwrite an existing file you
  must pass `overwrite: true` (it never silently clobbers).
- **`run_command`** (`sandbox run` in the CLI) — run any bash command in the sandbox (build, install,
  scaffolding, codemods). The working directory defaults to the app root; `cd`
  does not persist across calls, so use the `cwd` parameter or chain commands
  (`cd sub && cmd`). Timeout defaults to 120s (max 600s); output is capped at
  ~1 MB.
- **`create_checkpoint`** (`sandbox checkpoint` in the CLI) — save a named
  restore point the user can later roll back to. Takes an optional `name`
  (message/title; auto-generated if omitted). Any pending changes are **flushed
  and committed first** so the checkpoint anchors to your latest code; it then
  returns the checkpoint id, name, and git commit hash. Use it to mark a
  known-good state before or after a chunk of edits. (If a recent auto-commit
  can't be confirmed durable yet, it refuses with the retryable
  `COMMIT_FLUSH_PENDING` rather than checkpoint stale state — retry shortly.)

Example:

```
On appId <APP_ID>, use edit_file to change the homepage heading in
src/pages/Home.jsx from "Welcome" to "Welcome back". Show me the diff first
with dry_run, then apply it.
```

---

## 5. Preview and verify (the edit → check loop)

There is no live log-streaming tool, but you can close the feedback loop:

- **See it live:** `get_app_preview_url` brings up the dev server and returns
  the preview URL. Vite HMR reflects your edits as you make them.
- **Build status:** `get_app_status` returns `ready` / `processing` / `error`.
- **Surface build/type/lint errors on demand** with `run_command`:
  ```bash
  npm run build       # bundler/compile errors
  npx tsc --noEmit    # type errors
  npm run lint        # lint errors
  ```
- **Read the dev-server (Vite) logs** — the managed dev server writes to
  `/tmp/vite.log`. Tail it via `run_command` to see HMR/compile errors:
  ```bash
  tail -c 32000 /tmp/vite.log
  ```
  (This is outside the app tree, so it's only reachable through `run_command`,
  not the file tools — and therefore needs `sandbox:write`.)

A solid loop: `edit_file` → `npm run build` (or tail `/tmp/vite.log`) → fix any
errors → `get_app_preview_url` to eyeball it.

> **Browser-runtime errors** (a component that compiles but throws on render,
> a failing client API call) appear in the browser console, not in
> `/tmp/vite.log`. Open the preview URL to catch those.

---

## 6. How your changes persist

You don't need to "save." Every mutating call schedules a **debounced
auto-commit** (~5 seconds): the change is committed and pushed to Base44's code
storage, so it:

- survives sandbox death (the sandbox is recreated from the last commit),
- appears in the builder's Library/Data tabs,
- keeps backend-function deploys consistent, and
- is included when you publish the app.

Practical implications:

- There's a small loss window (~5s) — don't kill the session immediately after
  the last edit; give it a moment to commit.
- Edits to entities, agents, workflows, backend functions, and page routing are
  synced into Base44 automatically after the commit. Plain page/component/CSS
  edits live in git and need nothing extra.

---

## 7. Concurrency: you vs. the Base44 builder

You and the in-app Base44 builder can't mutate the same app at once:

- **While you're actively using the sandbox tools**, the Base44 builder chat is
  blocked ("An external agent is currently working on this app"). Your session
  is implicit — recent tool calls *are* the session; it ends after a short idle
  period (~10 min).
- **If the Base44 builder is mid-build**, your mutating tools return
  `BUILDER_BUSY`. Poll `get_app_status` and retry once it's `ready`. Read-only
  tools still work during a build.

---

## 8. Guardrails & limits

- **Paths are confined to the app.** File tools operate only within the app
  directory; traversal/absolute paths are rejected (`PATH_OUTSIDE_SANDBOX`).
- **`.agents/` is off-limits to file tools** (`PROTECTED_PATH`) — it holds
  agent-managed config and secrets (`.agents/.env`). Don't try to read or edit
  it through the file tools.
- **Rate limits** apply per app: reads ~120/min, mutations ~60/min, commands
  ~30/min. If you hit `RATE_LIMITED`, slow down.
- **`delete_file` isn't a dedicated tool** — delete via `run_command rm`.

### Error codes you may see

`NOT_AUTHORIZED` (missing scope/flag) · `APP_NOT_FOUND` (wrong id or no access)
· `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` ·
`EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (make `old_text` unique or use
`replace_all`) · `OVERWRITE_NOT_ALLOWED` (pass `overwrite: true`) · `TIMEOUT` ·
`OUTPUT_TRUNCATED` · `BUILDER_BUSY` ·
`COMMIT_FLUSH_PENDING` (a pending auto-commit isn't durable yet; retry shortly —
e.g. on `create_checkpoint`) · `RATE_LIMITED` · `BACKEND_ERROR`.

Messages are written so the agent can self-correct — read them and adjust.

---

## 9. Tips & tricks

- **Read before you write.** A quick `list_directory` + `read_file` (or `grep`)
  pass costs little and dramatically improves edit accuracy.
- **Use `dry_run` on `edit_file`** to confirm the diff before committing to a
  change, especially for multi-edit calls.
- **Prefer `edit_file` over `write_file`** for existing files — surgical edits
  avoid clobbering and produce a reviewable diff.
- **Read line ranges** with `read_file`'s `offset`/`limit` on large files
  instead of pulling the whole thing into context.
- **When something "looks broken," tail `/tmp/vite.log`** before guessing —
  it usually names the exact file and line.
- **Let it commit.** Pause a few seconds after your final edit so the auto-commit
  lands before you disconnect or publish.
- **Checkpoint known-good states.** Use `create_checkpoint` (`sandbox checkpoint`)
  to mark a restore point before or after a risky chunk of edits — it flushes
  pending changes first, so the user can always roll back to that point.
- **One agent at a time.** The feature is designed for a single external agent
  per app; don't run parallel sessions against the same app.

---

## 10. Local agents via the `base44 sandbox` CLI

If your agent runs on your machine, it can drive the same sandbox through the Base44 CLI instead of
MCP, authenticating with the Base44 CLI instead of OAuth. Same tools, same behavior, same error
codes (Section 8) — only the surface and auth differ.

**Auth.** Log in with the Base44 CLI (`base44 login`) — the same credential used for
`base44 functions deploy`. Like the projectless `base44 connectors` commands, the sandbox
subcommands resolve the app id from `--app-id`, then `BASE44_APP_ID`, then a local `.app.jsonc`;
no `config.jsonc` is required.

**Command names.** The CLI exposes each sandbox tool under a shorter name:

| MCP tool | CLI command |
|---|---|
| `list_directory` | `base44 sandbox ls` |
| `read_file` | `base44 sandbox read` |
| `write_file` | `base44 sandbox write` |
| `edit_file` | `base44 sandbox edit` |
| `run_command` | `base44 sandbox run` |
| `grep` | `base44 sandbox grep` |
| `create_checkpoint` | `base44 sandbox checkpoint` |

```bash
npx base44 sandbox read --app-id <APP_ID> src/App.jsx
```

`base44 sandbox checkpoint` takes an optional `--name` (message/title) and saves a restore point:

```bash
npx base44 sandbox checkpoint --app-id <APP_ID> --name "before refactor"
```

**Hand an agent the full reference** for a specific app (instructions, public, no
auth needed to fetch):

```
https://app.base44.com/api/sandbox/<APP_ID>/local-agent/readme.md
```

(The cloud/MCP equivalent is `.../api/sandbox/<APP_ID>/claude-web/readme.md`.)

Everything else in this skill — the edit→preview→verify loop (Section 5), persistence
(Section 6), concurrency (Section 7), and guardrails (Section 8) — applies identically; only the
surface and auth differ.

---

## 11. Connectors (OAuth integrations)

Beyond the sandbox file/shell tools, the Base44 MCP server exposes two tools for managing a
third-party OAuth connector (Google Calendar, Gmail, Slack, …) on an app. They don't touch the
sandbox filesystem — they operate on the app's connector state directly. Both take `appId`.

| Tool | Scope | Purpose |
|---|---|---|
| `list_connectors` | `apps:read` | List the app's connectors. With no `integrationTypes`, returns the full catalog (name, description, connected?, and — if connected — status and granted scopes). Pass `integrationTypes` for detail on specific ones. |
| `initiate_connector_connection` | `apps:write` | Connect (or re-scope) a connector. Inputs: `appId`, `integrationType`, `scopes`, optional `connectionConfig`. |

Two semantics to get right:

- **Declarative scopes (replace, not merge).** `initiate_connector_connection` sets the connector
  to **exactly** the `scopes` you pass. Omitted scopes are removed and the user is re-prompted to
  consent. **Always call `list_connectors` first**, then pass the complete desired set (existing
  scopes you want to keep **plus** any new ones).
- **OAuth needs a human.** The tool returns either `already_authorized: true` (nothing to do) or a
  `redirect_url` the **user** must open in a browser to sign in and consent — you can't complete it
  yourself. After they finish, call `list_connectors` again to verify and read the **granted**
  scopes (a provider may grant fewer than requested).

These need only `apps:read` / `apps:write` — **not** `sandbox:write`. Over the CLI surface
(Section 10), the equivalent is the projectless `base44 connectors` commands
(`list-available`, `initiate --integration-type <t> --scopes <s...> --app-id <id>`, `pull`), which
print the same authorization URL.

View saved version →

---
name: base44-sandbox
description: "Develop a Base44 app remotely inside Base44's cloud sandbox using your own agent — no local checkout and no deploy/push commands. The implementation is remote: writing a resource file into the sandbox is what ships it (backend functions, entities, and agents all auto-sync from the file you write), and OAuth connectors are set up against the remote app via MCP tools or the projectless `base44 connectors` CLI. This skill is the place for learning what you can author in the sandbox, how backend functions, entities, and agents are structured, and how to connect a connector without a local filesystem. Triggers on 'develop my Base44 app remotely', 'no local files', 'cloud sandbox', 'create an entity/agent remotely', 'connect a connector remotely', 'bring my own agent', or any work editing a Base44 app inside a sandbox."
---

# Base44 in the Cloud Sandbox

Author Base44 app code **inside Base44's cloud sandbox** with your own coding agent. There is no local checkout: you read, write, and run files through the sandbox tools (over MCP or the `base44 sandbox` CLI), and the platform builds and deploys from what you write.

For **how to connect** to the sandbox (MCP endpoint or the `base44 sandbox` CLI, the `read_file` / `write_file` / `edit_file` / `run_command` / `grep` / `list_directory` / `create_checkpoint` tools — which the CLI exposes under shorter names (`sandbox read` / `sandbox write` / `sandbox edit` / `sandbox run` / `sandbox grep` / `sandbox ls` / `sandbox checkpoint`), the edit→preview→verify loop, persistence, and concurrency), use the **`base44-remote-dev`** skill. This skill covers **what you can author and how** once you are connected.

> **Check these references first.** This skill and its siblings (`base44-remote-dev`, `base44-sdk`) are the source of truth — consult them before searching the web. See [Reference order & the complete README](#reference-order--the-complete-readme).

## ⚡ The mental model: writing the file *is* the deploy

You are working on a **remote** app, not a local checkout. The project-level CLI workflow does **not** apply — never run `base44 deploy`, `base44 functions deploy`, `base44 ... push`, `base44 create`, or `base44 scaffold`. They assume a local project and a manual deploy step that does not exist here.

Instead: **as soon as you write a resource file into the sandbox — a backend function, an entity, or an agent — the platform deploys/syncs it from there.** Your write is auto-committed (~5s debounce) and goes live. You do not run, and must not wait for, any `deploy` / `push` command.

**One exception — connectors.** OAuth connectors aren't authored as files; they're set up against the remote app by its id, either with the MCP connector tools or with the dedicated, projectless `base44 connectors` commands (which take `--app-id` and need no local project). See [Connectors](#connectors-oauth-integrations) below.

You *may* still use `run_command` (`sandbox run` in the CLI) for ordinary checks (e.g. `npm run build`, `npx tsc --noEmit`, `npm run lint`) and preview — that is verification, not deployment. See the edit→preview→verify loop in `base44-remote-dev`.

## What you can author today

| Resource | Status in the sandbox |
|----------|-----------------------|
| **Backend functions** (`base44/functions/`) | ✅ Supported — write the files; they deploy from the sandbox. |
| **Entities** (`base44/entities/`) | ✅ Supported — write the `.jsonc` schema file; it auto-syncs. No `entities push`. |
| **Agents** (`base44/agents/`) | ✅ Supported — write the `.jsonc` config file; it auto-syncs. No `agents push`. |
| **Frontend code** (`src/…`) | ✅ Supported — edit normally; HMR/preview reflects it. Use the **`base44-sdk`** skill for SDK API usage. |
| **Connectors** (OAuth integrations) | ✅ Supported — set up via the connect flow below (MCP tools or `base44 connectors`), **not** by writing files. |

## Backend functions

Backend functions live in `base44/functions/`, one directory per function (kebab-case name). In the sandbox you only need to create the **`entry.ts`** file directly under `base44/functions/<name>/` — **no `function.jsonc` is required** (the sandbox infers the function from the directory; the config file is ignored in this mode):

```
base44/functions/
  process-order/
    entry.ts
```

Entry file — functions run on **Deno** (not Node.js), export with `Deno.serve()`, and use the `npm:` prefix for npm packages:
```typescript
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);   // inherits the caller's auth
  const { orderId } = await req.json();
  const order = await base44.entities.Orders.get(orderId);
  return Response.json({ success: true, order });
});
```
Conventions:
- **Kebab-case** directory and function name; entry typically `entry.ts`.
- `createClientFromRequest(req)` for a client in the caller's auth context; `base44.asServiceRole.…` for admin-level operations.
- Read secrets with `Deno.env.get("KEY")` (configured in app settings).
- Return with `Response.json(body, { status })`; handle errors and set appropriate status codes.

That's enough to author functions correctly. For deeper detail and more examples (service role, secrets, common mistakes), see the `base44-cli` skill's reference: [`functions-create.md`](../base44-cli/references/functions-create.md) — but **ignore its "Deploying Functions" / CLI sections** and its **`function.jsonc`** guidance, which assume a local project and do not apply in the sandbox (here you only write `entry.ts`).

> **Calling the function from the frontend:** `base44.functions.invoke(name, data)` returns the **raw axios response** — your function's JSON is on **`.data`** (`const result = res.data`), not the top-level object, and it **throws on non-2xx** (error body at `err.response.data`). See the `base44-sdk` skill's [`functions.md`](../base44-sdk/references/functions.md) for details.

## Entities

One `.jsonc` file per entity in `base44/entities/`. Just write the file — it auto-syncs; **don't run `base44 entities push` or `deploy`.**

- **File name:** `{kebab-case}.jsonc` — e.g. `team-member.jsonc` for an entity named `TeamMember`.
- **Entity `name`:** PascalCase, alphanumeric only (`/^[a-zA-Z0-9]+$/`).
- **Field names:** `snake_case`.

```jsonc
// base44/entities/task.jsonc
{
  "name": "Task",
  "type": "object",
  "properties": {
    "title": { "type": "string", "description": "Task title" },
    "status": { "type": "string", "enum": ["todo", "doing", "done"], "default": "todo" },
    "due_date": { "type": "string", "format": "date" },
    "board_id": { "type": "string", "description": "Owning board" }
  },
  "required": ["title"]
}
```

Field types: `string`, `number`, `integer`, `boolean`, `array`, `object`, `binary`. String formats include `date`, `date-time`, `email`, `uri`, `uuid`, `file`, `richtext`. For full schema detail and row-level security (RLS), see the `base44-cli` references [`entities-create.md`](../base44-cli/references/entities-create.md) and [`rls-examples.md`](../base44-cli/references/rls-examples.md) — but **ignore their `entities push` / deploy sections**; the sandbox syncs the file for you.

## Agents

One `.jsonc` file per agent in `base44/agents/`. Just write the file — it auto-syncs; **don't run `base44 agents push` or `deploy`.**

- **File name:** `{agent_name}.jsonc` — e.g. `support_agent.jsonc`.
- **Agent `name`:** `/^[a-z0-9_]+$/` (lowercase, underscores, 1–100 chars).

```jsonc
// base44/agents/support_agent.jsonc
{
  "name": "support_agent",
  "description": "Brief description of what this agent does",
  "instructions": "Detailed instructions for the agent's behavior",
  "tool_configs": [
    { "entity_name": "tasks", "allowed_operations": ["read", "create", "update", "delete"] },
    { "function_name": "send_email", "description": "Send an email notification" }
  ],
  "whatsapp_greeting": "Hello! How can I help you today?"
}
```

Required: `name`, `description`, `instructions`. Optional: `tool_configs` (default `[]`), `whatsapp_greeting`. Tool configs are either an **entity tool** (`entity_name` + `allowed_operations`: any of `read`/`create`/`update`/`delete`) or a **backend-function tool** (`function_name` + `description`). For the full agent schema, see the **Agent Schema** section of the `base44-cli` skill's [`SKILL.md`](../base44-cli/SKILL.md) — but **ignore its `agents push` / `agents pull` / deploy commands**, which assume a local project; in the sandbox the file auto-syncs.

## Connectors (OAuth integrations)

Connectors (Google Calendar, Gmail, Slack, …) give your backend functions tokens to call third-party APIs. In remote-dev there are **no connector files to write** — you operate on the connector directly against the app by its id. Two surfaces, same backend and same behavior:

> **Declarative scopes — read before you set.** Connecting a connector **replaces** its scope set with exactly the scopes you pass (it does not merge). Any scope you omit is removed and the user is re-prompted to consent. **Always list the connector's current scopes first and pass the complete desired set** (the ones you want to keep **plus** any new ones).

> **OAuth needs a human.** Connecting returns an **authorization URL** the user must open in a browser to sign in and consent — you cannot complete it yourself. After they finish, re-list to confirm it's connected and to read the **granted** scopes (a provider may grant fewer than you requested).

### Over MCP (`base44-remote-dev` transport)

Two tools, both taking `appId`. Scopes: `list_connectors` needs `apps:read`; `initiate_connector_connection` needs `apps:write` (note: **not** `sandbox:write`).

1. **`list_connectors`** — `{ appId, integrationTypes? }`. With no `integrationTypes`, returns the full catalog; each entry has the connector's name, description, whether it's connected, and (if connected) its status and granted scopes. Pass `integrationTypes` for full detail on specific connectors.
2. **`initiate_connector_connection`** — `{ appId, integrationType, scopes, connectionConfig? }`. `scopes` is the **complete** desired set (see the declarative-scopes note). Returns either `already_authorized: true` (nothing to do) or a `redirect_url` for the user to open. After they sign in, call `list_connectors` again to verify.

```
On appId <APP_ID>: call list_connectors to read googlecalendar's current scopes,
then initiate_connector_connection for googlecalendar with the full scope set
(existing + the calendar.events scope I need). Give me the authorization URL.
```

### Over the CLI (projectless, `--app-id`)

These `base44 connectors` subcommands work **without a local project** — they resolve the app id from `--app-id`, then `BASE44_APP_ID`, then a local `.app.jsonc`. No `config.jsonc` is required.

```bash
# 1. See available integration types for the app
npx base44 connectors list-available --app-id <APP_ID>

# 2. Initialize the connector and start OAuth (sets it to EXACTLY these scopes).
#    Non-interactive: prints the authorization URL. Interactive: also opens the
#    browser and polls until authorized.
npx base44 connectors initiate --app-id <APP_ID> \
  --integration-type googlecalendar \
  --scopes https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events

# 3. (optional) Fetch the resulting connector config
npx base44 connectors pull --app-id <APP_ID> --dir ./connectors
```

`--scopes` accepts a space- or comma-separated list. As with MCP, the user must open the printed authorization URL to finish consent; afterwards `list-available` / `pull` reflects the connected state and granted scopes.

> This is the **only** Base44 CLI use that belongs in remote-dev — it targets a remote app by id with no local project and no deploy step. It is not a contradiction of the "no CLI" rule above, which is about local-project/deploy commands.

### Using a connected connector in code

Connecting only authorizes the connector. To actually call the third-party API, fetch its OAuth access token **inside a backend function** with the service-role connectors module — `base44.asServiceRole.connectors.getConnection(integrationType)` — and use the returned `accessToken` (and optional `connectionConfig`) in your own `fetch`:

```typescript
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);

  // App-scoped OAuth token — backend / service role only.
  const { accessToken, connectionConfig } =
    await base44.asServiceRole.connectors.getConnection("googlecalendar");

  const events = await fetch(
    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
    { headers: { Authorization: `Bearer ${accessToken}` } },
  ).then((r) => r.json());

  return Response.json({ events });
});
```

Notes: the connector is **app-scoped** (one connected account shared by all users); Base44 refreshes the token for you; you make the API calls. `getConnection()` replaces the deprecated `getAccessToken()`. For the full module reference (signatures, `connectionConfig`, the list of available services and their type identifiers), see the `base44-sdk` skill's [`connectors.md`](../base44-sdk/references/connectors.md).

## Reference order & the complete README

**Consult the references in this skill and its sibling skills (`base44-remote-dev`, `base44-sdk`) before searching the web.** They are the source of truth for the sandbox bridge, file/resource conventions, and SDK APIs — prefer them over general internet results, which are often stale or wrong for Base44.

For the complete, app-specific remote-dev reference (instructions + every endpoint, public, no auth needed to fetch), read the onboarding README for your app:

```
https://app.base44.com/api/sandbox/<APP_ID>/local-agent/readme.md
```

(The cloud/MCP equivalent is `…/api/sandbox/<APP_ID>/claude-web/readme.md`.) See the `base44-remote-dev` skill for the connection mechanics this README describes.

## Workflow in the sandbox

1. **Orient** — `list_directory` / `read_file` / `grep` (`sandbox ls` / `sandbox read` / `sandbox grep` in the CLI) to understand the app before changing anything.
2. **Author** — create or edit resource files (backend functions, entities, agents) and frontend code following the conventions above; set up connectors via the connect flow.
3. **Verify** — optionally `run_command` (`sandbox run`) `npm run build` / `npx tsc --noEmit`, and use `get_app_preview_url` to eyeball changes (see `base44-remote-dev`).
4. **Let it ship** — do **nothing** to deploy. Writing the file is the deploy; the auto-commit (~5s) persists and ships it. Pause a moment after your last edit before disconnecting so the commit lands.
5. **(Optional) Checkpoint** — mark a known-good restore point the user can roll back to with `create_checkpoint` (`base44 sandbox checkpoint --name "..."` in the CLI). It flushes pending changes first, so the checkpoint captures your latest code. See `base44-remote-dev` for details.

View saved version →

---
name: base44-sdk
description: "The base44 SDK is the library to communicate with base44 services. In projects, you use it to communicate with remote resources (entities, backend functions, ai agents) and to write backend functions. This skill is the place for learning about available modules and types. When you plan or implement a feature, you must learn this skill"
---

# Base44 Coder

Build apps on the Base44 platform using the Base44 JavaScript SDK.

## ⚡ IMMEDIATE ACTION REQUIRED - Read This First

This skill activates on ANY mention of "base44" or when a `base44/` folder exists. **DO NOT read documentation files or search the web before acting.**

**Your first action MUST be:**
1. Check if `base44/config.jsonc` exists in the current directory
2. If **YES** (existing project scenario):
   - This skill (base44-sdk) handles the request
   - Implement features using Base44 SDK
   - Do NOT use base44-cli unless user explicitly requests CLI commands
3. If **NO** (new project scenario):
   - Transfer to base44-cli skill for project initialization
   - This skill cannot help until project is initialized

## When to Use This Skill vs base44-cli

**Use base44-sdk when:**
- Building features in an **EXISTING** Base44 project
- `base44/config.jsonc` already exists in the project
- Base44 SDK imports are present (`@base44/sdk`)
- Writing JavaScript/TypeScript code using Base44 SDK modules
- Implementing functionality, components, or features
- User mentions: "implement", "build a feature", "add functionality", "write code for"
- User says "create a [type] app" **and** a Base44 project already exists

**DO NOT USE base44-sdk for:**
- ❌ Initializing new Base44 projects (use `base44-cli` instead)
- ❌ Empty directories without Base44 configuration
- ❌ When user says "create a new Base44 project/app/site" and no project exists
- ❌ CLI commands like `npx base44 create`, `npx base44 deploy`, `npx base44 login` (use `base44-cli`)

**Skill Dependencies:**
- `base44-sdk` assumes a Base44 project is **already initialized**
- `base44-cli` is a **prerequisite** for `base44-sdk` in new projects
- If user wants to "create an app" and no Base44 project exists, use `base44-cli` first

**State Check Logic:**
Before selecting this skill, verify:
- IF (user mentions "create/build app" OR "make a project"):
  - IF (directory is empty OR no `base44/config.jsonc` exists):
    → Use **base44-cli** (project initialization needed)
  - ELSE:
    → Use **base44-sdk** (project exists, build features)

## Quick Start

```javascript
// In Base44-generated apps, base44 client is pre-configured and available

// CRUD operations
const task = await base44.entities.Task.create({ title: "New task", status: "pending" });
const tasks = await base44.entities.Task.list();
await base44.entities.Task.update(task.id, { status: "done" });

// Get current user
const user = await base44.auth.me();
```

```javascript
// External apps
import { createClient } from "@base44/sdk";

// IMPORTANT: Use 'appId' (NOT 'clientId' or 'id')
const base44 = createClient({ appId: "your-app-id" });
await base44.auth.loginViaEmailPassword("user@example.com", "password");
```

## ⚠️ CRITICAL: Do Not Hallucinate APIs

**Before writing ANY Base44 code, verify method names against this table or [QUICK_REFERENCE.md](references/QUICK_REFERENCE.md).**

Base44 SDK has unique method names. Do NOT assume patterns from Firebase, Supabase, or other SDKs.

### Authentication - WRONG vs CORRECT

| ❌ WRONG (hallucinated) | ✅ CORRECT |
|------------------------|-----------|
| `signInWithGoogle()` | `loginWithProvider('google')` |
| `signInWithProvider('google')` | `loginWithProvider('google')` |
| `auth.google()` | `loginWithProvider('google')` |
| `signInWithEmailAndPassword(email, pw)` | `loginViaEmailPassword(email, pw)` |
| `signIn(email, pw)` | `loginViaEmailPassword(email, pw)` |
| `createUser()` / `signUp()` | `register({email, password})` |
| `onAuthStateChanged()` | `me()` (no listener, call when needed) |
| `currentUser` | `await auth.me()` |

### Functions - WRONG vs CORRECT

| ❌ WRONG (hallucinated) | ✅ CORRECT |
|------------------------|-----------|
| `functions.call('name', data)` | `functions.invoke('name', data)` |
| `functions.run('name', data)` | `functions.invoke('name', data)` |
| `callFunction('name', data)` | `functions.invoke('name', data)` |
| `httpsCallable('name')(data)` | `functions.invoke('name', data)` |

### Integrations - WRONG vs CORRECT

| ❌ WRONG (hallucinated) | ✅ CORRECT |
|------------------------|-----------|
| `ai.generate(prompt)` | `integrations.Core.InvokeLLM({prompt})` |
| `openai.chat(prompt)` | `integrations.Core.InvokeLLM({prompt})` |
| `llm(prompt)` | `integrations.Core.InvokeLLM({prompt})` |
| `sendEmail(to, subject, body)` | `integrations.Core.SendEmail({to, subject, body})` |
| `email.send()` | `integrations.Core.SendEmail({to, subject, body})` |
| `uploadFile(file)` | `integrations.Core.UploadFile({file})` |
| `storage.upload(file)` | `integrations.Core.UploadFile({file})` |

### Entities - WRONG vs CORRECT

| ❌ WRONG (hallucinated) | ✅ CORRECT |
|------------------------|-----------|
| `entities.Task.find({...})` | `entities.Task.filter({...})` |
| `entities.Task.findOne(id)` | `entities.Task.get(id)` |
| `entities.Task.insert(data)` | `entities.Task.create(data)` |
| `entities.Task.remove(id)` | `entities.Task.delete(id)` |
| `entities.Task.onChange(cb)` | `entities.Task.subscribe(cb)` |

## SDK Modules

| Module | Purpose | Reference |
|--------|---------|-----------|
| `entities` | CRUD operations on data models | [entities.md](references/entities.md) |
| `auth` | Login, register, user management | [auth.md](references/auth.md) |
| `agents` | AI conversations and messages | [base44-agents.md](references/base44-agents.md) |
| `functions` | Backend function invocation | [functions.md](references/functions.md) |
| `integrations` | AI, email, file uploads, custom APIs | [integrations.md](references/integrations.md) |
| `analytics` | Track custom events and user activity | [analytics.md](references/analytics.md) |
| `appLogs` | Log user activity in app | [app-logs.md](references/app-logs.md) |
| `users` | Invite users to the app | [users.md](references/users.md) |
| `asServiceRole.connectors` | App-scoped OAuth tokens (service role only) | [connectors.md](references/connectors.md) |
| `asServiceRole.sso` | SSO token generation (service role only) | [sso.md](references/sso.md) |

For client setup and authentication modes, see [client.md](references/client.md).

### TypeScript and type registries

Each reference file includes a "Type Definitions" section with TypeScript interfaces and types for the module's methods, parameters, and return values.

**Getting typed entities, functions, and agents:** The Base44 CLI generates types from your project resources (entities, functions, agents), including augmentations to `EntityTypeRegistry`, `FunctionNameRegistry`, and `AgentNameRegistry`, and wires them into your project so you get autocomplete and type checking without manual setup. For how to generate types, use the **base44-cli** skill.

**Manual augmentation:** You can instead augment the registries yourself in a `.d.ts` file; see the Type Definitions sections in [entities.md](references/entities.md), [functions.md](references/functions.md), and [base44-agents.md](references/base44-agents.md).

## Installation

Install the Base44 SDK:

```bash
npm install @base44/sdk
```

**Important:** Never assume or hardcode the `@base44/sdk` package version. Always install without a version specifier to get the latest version.

## Creating a Client (External Apps)

When creating a client in external apps, **ALWAYS use `appId` as the parameter name**:

```javascript
import { createClient } from "@base44/sdk";

// ✅ CORRECT
const base44 = createClient({ appId: "your-app-id" });

// ❌ WRONG - Do NOT use these:
// const base44 = createClient({ clientId: "your-app-id" });  // WRONG
// const base44 = createClient({ id: "your-app-id" });        // WRONG
```

**Required parameter:** `appId` (string) - Your Base44 application ID

**Optional parameters:**
- `token` (string) - Pre-authenticated user token
- `options` (object) - Configuration options
  - `options.onError` (function) - Global error handler

**Example with error handler:**
```javascript
const base44 = createClient({
  appId: "your-app-id",
  options: {
    onError: (error) => {
      console.error("Base44 error:", error);
    }
  }
});
```

## Module Selection

**Working with app data?**
- Create/read/update/delete records → `entities`
- Import data from file → `entities.importEntities()`
- Realtime updates → `entities.EntityName.subscribe()`

**User management?**
- Login/register/logout → `auth`
- Get current user → `auth.me()`
- Update user profile → `auth.updateMe()`
- Invite users → `users.inviteUser()`

**AI features?**
- Chat with AI agents → `agents` (requires logged-in user)
- Create new conversation → `agents.createConversation()`
- Manage conversations → `agents.getConversations()`
- Generate text/JSON with AI → `integrations.Core.InvokeLLM()`
- Generate images → `integrations.Core.GenerateImage()`

**Custom backend logic?**
- Run server-side code → `functions.invoke()`
- Need admin access → `base44.asServiceRole.functions.invoke()`

**External services?**
- Send emails → `integrations.Core.SendEmail()`
- Upload files → `integrations.Core.UploadFile()`
- Custom APIs → `integrations.custom.call()`
- App-scoped OAuth (app builder's account) → `asServiceRole.connectors.getConnection()` (backend only)

**Tracking and analytics?**
- Track custom events → `analytics.track()`
- Log page views/activity → `appLogs.logUserInApp()`

## Common Patterns

### Filter and Sort Data

```javascript
const pendingTasks = await base44.entities.Task.filter(
  { status: "pending", assignedTo: userId },  // query
  "-created_date",                             // sort (descending)
  10,                                          // limit
  0                                            // skip
);
```

### Protected Routes (check auth)

```javascript
const user = await base44.auth.me();
if (!user) {
  // Navigate to your custom login page
  navigate('/login', { state: { returnTo: window.location.pathname } });
  return;
}
```

### Backend Function Call

```javascript
// Frontend
const result = await base44.functions.invoke("processOrder", {
  orderId: "123",
  action: "ship"
});

// Backend function (Deno)
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const { orderId, action } = await req.json();
  // Process with service role for admin access
  const order = await base44.asServiceRole.entities.Orders.get(orderId);
  return Response.json({ success: true });
});
```

### Service Role Access

Use `asServiceRole` in backend functions for admin-level operations:

```javascript
// User mode - respects permissions
const myTasks = await base44.entities.Task.list();

// Service role - full access (backend only)
const allTasks = await base44.asServiceRole.entities.Task.list();
const token = await base44.asServiceRole.connectors.getAccessToken("slack");
```

## Frontend vs Backend

| Capability | Frontend | Backend |
|------------|----------|---------|
| `entities` (user's data) | Yes | Yes |
| `auth` | Yes | Yes |
| `agents` | Yes | Yes |
| `functions.invoke()` | Yes | Yes |
| `functions.fetch()` | Yes | Yes |
| `integrations` | Yes | Yes |
| `analytics` | Yes | Yes |
| `appLogs` | Yes | Yes |
| `users` | Yes | Yes |
| `asServiceRole.*` | No | Yes |
| `asServiceRole.connectors` (app OAuth) | No | Yes |
| `asServiceRole.sso` | No | Yes |

Backend functions use `Deno.serve()` and `createClientFromRequest(req)` to get a properly authenticated client.

Referenced files: 13

View saved version →

---
name: base44-troubleshooter
description: Troubleshoot production issues using backend function logs. Use when investigating app errors, debugging function calls, or diagnosing production problems in Base44 apps.
---

# Troubleshoot Production Issues

## Prerequisites

Verify authentication before fetching logs:

```bash
npx base44 whoami
```

If not authenticated or token expired, instruct user to run `npx base44 login`.

Must be run from the project directory (where `base44/.app.jsonc` exists):

```bash
cat base44/.app.jsonc
```

## Available Commands

| Command | Description | Reference |
|---------|-------------|-----------|
| `base44 logs` | Fetch function logs for this app | [project-logs.md](references/project-logs.md) |

## Troubleshooting Flow

### 1. Check Recent Errors

Start by pulling the latest errors across all functions:

```bash
npx base44 logs --level error
```

### 2. Drill Into a Specific Function

If you know which function is failing:

```bash
npx base44 logs --function <function_name> --level error
```

### 3. Inspect a Time Range

Correlate with user-reported issue timestamps:

```bash
npx base44 logs --function <function_name> --since <start_time> --until <end_time>
```

### 4. Analyze the Logs

- Look for stack traces and error messages in the output
- Check timestamps to correlate with user-reported issues
- Use `--limit` to fetch more entries if the default 50 isn't enough

Referenced files: 2