Build and deploy Base44 full-stack apps with CLI project management and JavaScript/TypeScript SDK development skills

version
1.0.0-beta.1
GitHub stars
94

Install

/plugin install base44@base44-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add base44/skills.

Contents

Discovered from source

Skills 12

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 YES (existing project scenario):
    • Transfer to base44-sdk skill for implementation
    • This skill only handles CLI commands (login, deploy, entities push)
    • Except running the app locally — stays here. Read Running Local Development before starting a dev server: one way of running hits production data.
  3. If NO, decide between two initialization paths:
    • Provisioned app — the Base44 app already exists because it was just provisioned through a Stripe Projects / projects.dev flow, OR BASE44_APP_ID (or BASE44_PROJECTS_BASE44_APP_ID) is present in the environment or a .env/.env.local file:
      • Run npx base44 scaffold to set up local files for that existing app
      • DO NOT run npx base44 create — that creates a second, duplicate app. See scaffold.md.
    • New project — no app exists yet and none was provisioned:
      • This skill (base44-cli) handles the request; guide the user through npx base44 create
      • Do NOT activate base44-sdk yet

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:

    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:
      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.

Provisioned via Stripe Projects / projects.dev? When the app was provisioned through that flow, the CLI seeds authentication from the BASE44_ACCESS_TOKEN / BASE44_REFRESH_TOKEN environment variables it injects (the BASE44_PROJECTS_*-prefixed names are normalized automatically). In that case npx base44 whoami already succeeds and you do not need an interactive npx base44 login.

Workspace API key set? If the BASE44_API_KEY environment variable is set to a workspace API key (prefixed b44k_), the CLI authenticates with it directly — npx base44 whoami and other commands succeed without an interactive login.

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
  • Setting up local files for an existing app that was provisioned externally (e.g., through a Stripe Projects / projects.dev flow) → use scaffold
  • 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 (base44/config.jsonc exists): → Use base44-sdk (project exists, build features)
    • ELSE IF (app was provisioned externally — BASE44_APP_ID/BASE44_PROJECTS_BASE44_APP_ID set, or a Stripe Projects / projects.dev flow just ran): → Use base44-cli → npx base44 scaffold (set up local files for the existing app; do NOT create)
    • ELSE: → Use base44-cli → npx base44 create (new project initialization needed)

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)
│   │   └── my-function/
│   │       └── entry.ts
│   ├── actors/                  # Realtime actors (optional)
│   │   └── ChatRoom/
│   │       └── entry.ts
│   ├── agents/                  # Agent configurations (optional)
│   │   └── support_agent.jsonc
│   ├── agent-skills/            # Agent skill instructions (optional)
│   │   └── pdf-export.md
│   └── 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/*/entry.ts - Backend function entry point
  • base44/actors/*/entry.ts - Realtime actor entry point (optional)
  • base44/agents/*.jsonc - Agent configurations (optional)
  • base44/agent-skills/*.md - Agent skill instructions (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:

{
  "name": "My App",                    // Required: project name
  "description": "App description",    // Optional: project description
  "visibility": "public",              // Optional: "public" | "private" | "workspace"
  "entitiesDir": "./entities",         // Optional: default "entities"
  "functionsDir": "./functions",       // Optional: default "functions"
  "actorsDir": "./actors",             // Optional: default "actors"
  "agentsDir": "./agents",             // Optional: default "agents"
  "agentSkillsDir": "./agent-skills",  // Optional: default "agent-skills"
  "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:

PropertyDescriptionDefault
nameProject name (required)-
descriptionProject description-
visibilityApp visibility: public, private, or workspace-
entitiesDirDirectory for entity schemas"entities"
functionsDirDirectory for backend functions"functions"
actorsDirDirectory for realtime actors"actors"
agentsDirDirectory for agent configs"agents"
agentSkillsDirDirectory for agent skill instructions"agent-skills"
connectorsDirDirectory for connector configs"connectors"
site.installCommandCommand to install dependencies-
site.buildCommandCommand to build the project-
site.serveCommandCommand to run dev server-
site.outputDirectoryBuild output directory for deployment-

Installation

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

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:

npx base44 <command>

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

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.

Resolution order: --app-id flag → BASE44_APP_ID environment variable → local base44/.app.jsonc

This is useful when you want to inspect or operate on an app without switching into a linked project directory. Common examples:

# Run a one-off script against a specific app
cat ./script.ts | npx base44 exec --app-id app_123

# Fetch logs for a deployed app without a local checkout
npx base44 logs --app-id app_123 --level error

Use --app-id for app-scoped commands like exec and logs.

Do not use --app-id for commands that need local project files:

  • base44 create creates a new app, so it rejects --app-id
  • base44 dev runs from a linked local project, so it rejects --app-id
  • base44 deploy still requires a local project directory because it reads local resources

Global --json Option

The CLI has a global --json option that makes commands emit a machine-readable JSON document on stdout instead of human-oriented output. It also forces non-interactive mode (spinners/status messages/logs move to stderr), so stdout stays pure JSON — safe to pipe into jq or another program.

npx base44 connectors list-available --json
npx base44 logs --app-id app_123 --json

Available Commands

Authentication

CommandDescriptionReference
base44 loginAuthenticate with Base44 using device code flowauth-login.md
base44 logoutLogout from current deviceauth-logout.md
base44 whoamiDisplay current authenticated userauth-whoami.md

Project Management

CommandDescriptionReference
base44 createCreate a new Base44 project from a templatecreate.md ⚠️ MUST READ
base44 scaffoldScaffold a local project for an existing Base44 app (by app ID)scaffold.md
base44 linkLink an existing local project to Base44link.md
base44 ejectDownload the code for an existing Base44 projecteject.md
base44 dashboard openOpen the app dashboard in your browserdashboard.md
base44 visibility <level>Set the app's visibility on the server (public, private, or workspace)visibility.md

Workspace Management

Workspaces (a.k.a. organizations) group apps under shared membership. By default base44 create/base44 link --create use your personal workspace; pass -w, --workspace <id> to target another one.

CommandDescriptionReference
base44 workspace listList the workspaces you belong toworkspace-list.md
base44 workspace get <workspace-id>Show details for a single workspace by IDworkspace-get.md
base44 workspace move [workspace-id]Move the current app to another workspaceworkspace-move.md

Development

CommandDescriptionReference
base44 devStart local development for your Base44 backend, and your frontend too when site.serveCommand is configureddev.md
base44 dev --remoteServe the frontend locally against the production backenddev.md

Deployment

CommandDescriptionReference
base44 buildBuild the site with its app id injected — use instead of a bare npm run build—
base44 deployDeploy all resources (entities, functions, actors, agents, agent skills, connectors, auth config, and site); asks whether to build first, or pass --build / --no-builddeploy.md

Entity Management

Action / CommandDescriptionReference
Create EntitiesDefine entities in base44/entities folderentities-create.md
base44 entities pushPush local entities to Base44entities-push.md
RLS PatternsRow-level security examples and operatorsrls-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:

{
  "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.

Function Management

Action / CommandDescriptionReference
Create FunctionsDefine functions in base44/functionsfunctions-create.md
base44 functions deploy [names...] [--force]Deploy local functions to Base44; optionally target specific functions or prune removed onesfunctions-deploy.md
base44 functions delete <names...>Delete one or more deployed functions from Base44functions-delete.md
base44 functions listList all deployed functions on Base44 remotefunctions-list.md
base44 functions pull [name]Pull deployed functions from Base44 to local filesfunctions-pull.md

Workflow Runs

Workflows are the automation system (cron schedules, entity triggers, connector events, in-app agent actions). These commands are read-only: they answer "what workflows exist" and "did my scheduled work fail, and why".

CommandDescriptionReference
base44 workflows listList this app's workflows with status and run summaryworkflows-list.md
base44 workflows runs [--status <s>] [--since <t>]List workflow runs, newest first; failed runs include the underlying errorworkflows-runs.md

Actor Management

Actors are stateful realtime server rooms over WebSockets — one live instance per room id, shared by every client connected to that id. Use them for multiplayer sessions, collaborative boards, presence and live cursors, in-room chat, and live auctions.

Actors use direct connections with SDK-managed authentication. Use verified conn.identity for user attribution and this.client.asServiceRole to persist validated room results. Actors receive no app secrets; put secret-dependent operations in a backend function. See actors-create.md for the authoring contract.

Action / CommandDescriptionReference
Create ActorsDefine actors in base44/actorsactors-create.md
base44 actors deploy [names...]Deploy local actors to Base44; optionally target specific actorsactors-deploy.md
base44 actors delete <names...>Tear down deployed actors (destroys the published script)actors-deploy.md
Actor Layout (Quick Reference)

File naming: base44/actors/{ActorName}/entry.ts — the folder is the actor's identity.

// base44/actors/ChatRoom/entry.ts
import { Actor } from "base44:runtime/actors";

export default class ChatRoom extends Actor {
  handleConnect(conn) { conn.send({ type: "welcome" }); }   // this client only
  handleMessage(conn, msg) {
    // Always validate: the payload is attacker-controlled and msg can even be null.
    if (msg?.type !== "message" || typeof msg.text !== "string") return;
    this.broadcast({ type: "message", text: msg.text.slice(0, 2000) });   // the whole room
  }
  handleClose(conn) {}
}

Naming rules: actor names become a JavaScript class binding and the WebSocket connect handler — they must match [A-Za-z_][A-Za-z0-9_]* (max 128 chars, no /, -, . or :), must not be a JS reserved word, must not collide with a backend function name, and cannot be nested in subfolders. The CLI checks all of this locally before uploading; a folder with a dot in its name is skipped instead (so ChatRoom.bak/ is safe scratch space).

  • Valid: ChatRoom, BoardRoom, Lobby
  • Invalid: chat-room, games/Arena, class

Required: entry.ts (or entry.js) that default-exports a class extending Actor from base44:runtime/actors. In TypeScript, also declare handleTick() {} — it is an abstract member of Actor.

Differs from functions: only the actor's own folder is uploaded (no base44/shared/), no --force prune, no list/pull commands, no local base44 dev runtime, names cannot be path-like, and automations are not supported.

For complete documentation, see actors-create.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 / CommandDescriptionReference
Create AgentsDefine agents in base44/agents folderSee Agent Schema below
base44 agents pullPull remote agents to local filesagents-pull.md
base44 agents pushPush local agents to Base44agents-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:

{
  "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" },
    // Server route tool - gives agent access to one of a full-stack app's server routes
    { "tool_name": "order_summary", "route_path": "/api/orders/summary", "method": "get", "description": "Summarize the user's recent orders" }
  ],
  "memory_config": {                 // Optional: lets the agent remember facts across conversations
    "enabled": true,
    "scope": "both",                 // "global" | "user" | "both"
    "include_other_conversation_context": false,
    "instructions": null
  },
  "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 []), memory_config, whatsapp_greeting

Tool config types:

  • Entity tools: entity_name + allowed_operations (array of: read, create, update, delete)
  • Backend function tools: function_name + description
  • Server route tools (full-stack apps): tool_name (1-64 chars of letters, digits, _, -) + route_path (app-relative, starts with a single /, no query string) + method (get|post|put|patch|delete, default post) + description (default "agent server route")

Memory config fields (all optional, see agents-push.md for details): enabled (bool, default true), scope (global|user|both, default both), include_other_conversation_context (bool, default false), instructions (string|null, default null)

Agent Skills Management

Agent skills are reusable Markdown instructions that extend what your app's AI agents know how to do. Use these commands to manage them.

Action / CommandDescriptionReference
Create Agent SkillsDefine skills in base44/agent-skills folderagent-skills-push.md
base44 agent-skills pullPull remote agent skills to local filesagent-skills-pull.md
base44 agent-skills pushPush local agent skills to Base44agent-skills-push.md

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

Agent Skill Schema (Quick Reference)

File naming: base44/agent-skills/{skill-name}.md (e.g., pdf-export.md)

Schema template:

---
description: Export the current report as a PDF and attach it to the conversation.
---

Use this skill when the user asks to export, download, or share a report as a PDF.

1. Call the `generate_report_pdf` function with the current report's entity ID.
2. Attach the returned file URL in your reply.

Naming rules: Skill names (the file name minus .md) must match pattern /^[a-z0-9]+(-[a-z0-9]+)*$/ (lowercase, hyphen-separated, 1-64 chars)

  • Valid: pdf-export, order-lookup
  • Invalid: PdfExport, pdf_export

Required fields: description (frontmatter, 1-1024 chars), body (Markdown content, 1-15000 chars)

For complete documentation, see agent-skills-push.md.

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 / CommandDescriptionReference
Create ConnectorsDefine connectors in base44/connectors folderconnectors-create.md
base44 connectors list-availableList all available integration types from Base44connectors-list-available.md
base44 connectors initiate --integration-type <t> [--scopes <s...>]Initialize a connector and start its OAuth flow; works projectless with --app-idconnectors-initiate.md
base44 connectors pullPull remote connectors to local filesconnectors-pull.md
base44 connectors push [--force]Push local connectors to Base44; --force also removes remote ones not found locallyconnectors-push.md

Note: connectors push adds and updates remote connectors (and triggers OAuth for new OAuth connectors), but only removes remote connectors missing locally with --force — the same rule as functions deploy. deploy never removes connectors. connectors pull is a full sync: it 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:

{
  "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 for details.

For complete documentation, see connectors-create.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.

CommandDescriptionReference
base44 auth password-login <enable|disable>Enable or disable username & password authenticationauth-password-login.md
base44 auth social-login <provider> <enable|disable>Enable or disable social login (google, microsoft, facebook, apple)auth-social-login.md
base44 auth sso <enable|disable>Configure SSO identity provider (google, microsoft, github, okta, custom)auth-sso.md
base44 auth pullPull auth config from Base44 to local filesauth-pull.md
base44 auth pushPush local auth config to Base44auth-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.

CommandDescriptionReference
base44 secrets listList the names of all secretssecrets-list.md
base44 secrets setSet one or more secrets (KEY=VALUE or --env-file)secrets-set.md
base44 secrets delete <key>Delete a secret by namesecrets-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 scripted workflows.

CommandDescriptionReference
base44 execRun a script (via stdin) with the Base44 SDK pre-authenticatedexec.md

Type Generation

CommandDescriptionReference
base44 types generateGenerate TypeScript types (types.d.ts) from entities, functions, actors, agents, and connectorstypes-generate.md

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

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

Site Management

CommandDescriptionReference
base44 site deployDeploy built site files to Base44 hostingsite-deploy.md
base44 site openOpen the deployed site in your browsersite-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).

Any Other API Operation

For a Base44 platform task with no dedicated command above (custom domains, URL redirects, SEO settings, app users, collaborators and ownership, analytics, security scans, workspace members and groups, CSV imports, and more), find and call the public API endpoint directly with base44 api. It covers the Apps API and Workspace API with your CLI login, through the server's OpenAPI spec.

Prefer a dedicated command only when it does exactly what was asked (base44 secrets, base44 functions, base44 logs, base44 deploy, and the rest of this skill). If it also does something the user didn't ask for (read its reference first), use base44 api instead.

The API covers apps and workspaces, not your own Base44 account: there is no operation for your password, email or profile. Send the user to the Base44 web app for those.

The flow:

  1. Find the endpoint: npx base44 api search "<what you want to do>", or browse with api catalog [area], or api grep <regex> when search misses. Each result's endpoint (e.g. "GET /api/apps/{app_id}/custom-domains") is the method and path to pass on as is.
  2. Read its contract: npx base44 api fetch <METHOD> <path> --help | jq '.description, .parameters, .requestBodySchema, .responseSchema'. Read the description before calling: the top search result is not always the right operation.
  3. Call it: npx base44 api fetch <METHOD> <path> [--body <json>]. Add --read-only while only looking.
CommandDescriptionReference
base44 api search <text...>Search every public API operation by what it doesapi-search.md
base44 api catalog [area]List the API's areas, or every operation in one areaapi-catalog.md
base44 api grep <pattern>Search the API spec with a regular expression, for when search missesapi-grep.md
base44 api fetch <METHOD> <path>Call an operation with your login; add --help after the path for its contractapi-fetch.md ⚠️ READ BEFORE CALLING

Quick Start

  1. Install the CLI in your project:

    npm install --save-dev base44
    
  2. Authenticate with Base44:

    npx base44 login
    
  3. Create a new project (ALWAYS provide name and --path flag):

    npx base44 create my-app --path .
    
  4. Run local development:

    npx base44 dev
    
  5. Build and deploy everything:

    npx base44 deploy --build -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 actors deploy - Deploy realtime actors only
  • npx base44 actors delete <name> - Tear down a deployed actor
  • npx base44 agents push - Push agents only
  • npx base44 agent-skills push - Push agent skills 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 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

# If you have base44/config.jsonc but no .app.jsonc
npx base44 link --create --name my-app

Running Local Development

Always run through the CLI — two modes:

CommandBackend + data
npx base44 devlocal — throwaway, empty each start, gone on stop
npx base44 dev --remoteproduction — the real app's live data

base44 dev starts the local backend (entities, functions, auth) and also serves your frontend when base44/config.jsonc sets site.serveCommand; a backend-only project needs nothing else. --remote runs only the frontend against the real backend, so it needs both a linked project and site.serveCommand.

Don't run npm run dev yourself: without the env vars the CLI injects, the app has no backend to reach — the dev server prints which command to use instead.

Default to npx base44 dev. Under --remote every write hits the live app. The vite startup line names the backend either way: [base44] Proxy enabled: /api -> <target>. Say which you started. Options: dev.md.

Deploying All Changes

# Generate types (optional, for TypeScript projects)
npx base44 types generate

# Deploy everything (entities, functions, and site), building the site first
npx base44 deploy --build -y

Build through the CLI, not with npm run build: npx base44 build injects VITE_BASE44_APP_ID, which a bare npm run build leaves unset — the bundle then can't resolve its own app and every API call on the deployed site fails. npx base44 deploy asks whether to build first; --build / --no-build answers up front (non-interactive defaults to upload-only, so CI is unchanged).

Generating TypeScript Types

# Generate types from entities, functions, actors, 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, actors, agents, or connectors to keep your types in sync. No authentication required.

Deploying Individual Resources

# 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

# Deploy only actors (all)
npx base44 actors deploy
# Deploy specific actors
npx base44 actors deploy ChatRoom BoardRoom
# Tear down a deployed actor
npx base44 actors delete ChatRoom

# Push only agents
npx base44 agents push

# Push only agent skills
npx base44 agent-skills 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

# 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

ErrorSolution
Not authenticatedRun npx base44 login first
No entities foundEnsure entities exist in base44/entities/ directory
Entity not recognizedEnsure file uses kebab-case naming (e.g., team-member.jsonc not TeamMember.jsonc)
No functions foundEnsure functions exist in base44/functions/ with entry.ts or entry.js
No actors foundEnsure actors exist as base44/actors/<ActorName>/entry.ts (never directly in base44/actors/)
Invalid actor nameActor names must match [A-Za-z_][A-Za-z0-9_]* (no /, -, . or :), avoid JS reserved words, and cannot be nested. Caught locally, before any upload
actors cannot be nestedFlatten to base44/actors/<ActorName>/entry.ts, or rename a helper you called entry.ts — every entry file under base44/actors/ counts as an actor
Actor and function share a nameThey deploy into one namespace — rename one of them
Actor file rejected in the functions bucketA file importing base44:runtime/actors must live at base44/actors/<ActorName>/entry.ts — move it out of base44/functions/
No agents foundEnsure agents exist in base44/agents/ directory with valid .jsonc configs
Invalid agent nameAgent names must be lowercase alphanumeric with underscores only
No agent skills foundEnsure skill files exist in base44/agent-skills/ directory with valid .md files
Invalid skill fileSkill file name must be lowercase-hyphenated and include a description in its frontmatter
Push cancelled / requires --yesagents push, agent-skills push, entities push, and connectors push --force are destructive — confirm interactively or pass -y/--yes in CI/non-interactive mode
No connectors foundEnsure connectors exist in base44/connectors/ directory with valid .jsonc configs
Invalid connector typeRun npx base44 connectors list-available to see valid types
Duplicate connector typeEach connector type can only be defined once per project
Connector authorization timeoutRe-run npx base44 connectors push and complete the OAuth flow in your browser
No site configuration foundCheck that site.outputDirectory is configured in project config
Site deployment failsEnsure the site was built first (npx base44 build, or npx base44 deploy --build) and the build succeeded
Deployed site's API calls all failThe bundle was built without its app id — rebuild with npx base44 build, not a bare npm run build, and redeploy
Update available messageIf prompted to update, run npm install -g base44@latest (or use npx for local installs)

Base44 actors

One actor instance per room id; the actor is authoritative, clients send operations. Writing the entry file deploys the actor.

Requires the Builder plan or above. The workspace's entitlement is reported by the agent-profile endpoint; on a lower plan the platform rejects the operation.

Pick the reference for this app

Determine the app profile first. Call GET /api/apps/{app_id}/agent-profile (over the Base44 MCP execute_api tool, or with your Base44 CLI token); it returns the framework, app type, runtime, entitlements and the exact reference files to read. Without it, detect from the project files: src/routes/__root.* and src/routeTree.gen.ts mean TanStack Start; app/_layout.* means a native mobile (Expo) app; otherwise it is a Vite SPA.

ProfileRead
Web app, Vite SPA (the default web template)Realtime actors (web apps)
Web app, TanStack StartRealtime actors (web apps)
Native mobile app (Expo, React Native)Realtime actors (mobile apps)

Base44 agents

An agent is a .jsonc file under base44/agents/; writing it defines the agent. Build the conversation UI with the agents SDK, or run a code agent on the AI gateway. In-app agents are available on web apps only; native mobile (Expo) apps do not support them.

Pick the reference for this app

Determine the app profile first. Call GET /api/apps/{app_id}/agent-profile (over the Base44 MCP execute_api tool, or with your Base44 CLI token); it returns the framework, app type, runtime, entitlements and the exact reference files to read. Without it, detect from the project files: src/routes/__root.* and src/routeTree.gen.ts mean TanStack Start; app/_layout.* means a native mobile (Expo) app; otherwise it is a Vite SPA.

ProfileRead
Web app, Vite SPA (the default web template)Agents (Vite SPA: tools are backend functions)
Web app, TanStack StartAgents (TanStack Start: tools are server routes)

Base44 backend functions

A Vite SPA app runs server code as backend functions; a TanStack Start app runs it as server functions and server routes inside its own project. Writing the file deploys it.

Requires the Builder plan or above. The workspace's entitlement is reported by the agent-profile endpoint; on a lower plan the platform rejects the operation.

Pick the reference for this app

Determine the app profile first. Call GET /api/apps/{app_id}/agent-profile (over the Base44 MCP execute_api tool, or with your Base44 CLI token); it returns the framework, app type, runtime, entitlements and the exact reference files to read. Without it, detect from the project files: src/routes/__root.* and src/routeTree.gen.ts mean TanStack Start; app/_layout.* means a native mobile (Expo) app; otherwise it is a Vite SPA.

ProfileRead
Web app, Vite SPA (the default web template)Backend functions (Vite SPA)
Web app, TanStack StartServer functions and server routes (TanStack Start)
Native mobile app (Expo, React Native)Backend functions (mobile apps)

Base44 connectors

Connectors are configured against the app, not authored as files: list the catalog, connect with the complete scope set, then read tokens in server code.

Requires the Builder plan or above. The workspace's entitlement is reported by the agent-profile endpoint; on a lower plan the platform rejects the operation.

Pick the reference for this app

Determine the app profile first. Call GET /api/apps/{app_id}/agent-profile (over the Base44 MCP execute_api tool, or with your Base44 CLI token); it returns the framework, app type, runtime, entitlements and the exact reference files to read. Without it, detect from the project files: src/routes/__root.* and src/routeTree.gen.ts mean TanStack Start; app/_layout.* means a native mobile (Expo) app; otherwise it is a Vite SPA.

ProfileRead
Web app, Vite SPA (the default web template)App connectors (Vite SPA)
Web app, TanStack StartApp connectors (TanStack Start)
Native mobile app (Expo, React Native)App connectors (mobile apps)

Base44 entities

Entities are JSON-schema objects stored as base44/entities/<Name>.jsonc; writing the file is what defines the data model. The platform applies each entity's rls rules on every app-user request.

Pick the reference for this app

Determine the app profile first. Call GET /api/apps/{app_id}/agent-profile (over the Base44 MCP execute_api tool, or with your Base44 CLI token); it returns the framework, app type, runtime, entitlements and the exact reference files to read. Without it, detect from the project files: src/routes/__root.* and src/routeTree.gen.ts mean TanStack Start; app/_layout.* means a native mobile (Expo) app; otherwise it is a Vite SPA.

For every app

ProfileRead
Web app, Vite SPA (the default web template)Entities and the entity SDK (web apps)
Web app, TanStack StartEntities and the entity SDK (web apps)
Native mobile app (Expo, React Native)Entities and the entity SDK (mobile apps)

Base44 frontend

The builder's own frontend rules for Base44 web and native mobile apps. Pick the reference for the app's framework; the TanStack reference ends with a worked example.

Pick the reference for this app

Determine the app profile first. Call GET /api/apps/{app_id}/agent-profile (over the Base44 MCP execute_api tool, or with your Base44 CLI token); it returns the framework, app type, runtime, entitlements and the exact reference files to read. Without it, detect from the project files: src/routes/__root.* and src/routeTree.gen.ts mean TanStack Start; app/_layout.* means a native mobile (Expo) app; otherwise it is a Vite SPA.

ProfileRead
Web app, Vite SPA (the default web template)Web app, Vite SPA
Web app, TanStack StartWeb app, TanStack Start
Native mobile app (Expo, React Native)Native mobile app (Expo, React Native, NativeWind)

Base44 integrations sdk

File uploads and signed URLs are called from the client SDK; every other Core integration runs in server code on an app with core-integration control, the default for new apps (profile core_integrations: backend_functions_only). The endpoint schemas below are the ones the platform serves today.

Pick the reference for this app

Determine the app profile first. Call GET /api/apps/{app_id}/agent-profile (over the Base44 MCP execute_api tool, or with your Base44 CLI token); it returns the framework, app type, runtime, entitlements and the exact reference files to read. Without it, detect from the project files: src/routes/__root.* and src/routeTree.gen.ts mean TanStack Start; app/_layout.* means a native mobile (Expo) app; otherwise it is a Vite SPA.

ProfileRead
Web app, Vite SPA (the default web template)Integrations and analytics SDK (Vite SPA)
Web app, TanStack StartIntegrations and analytics SDK (TanStack Start)
Native mobile app (Expo, React Native)Integrations SDK (mobile apps)

Base44 platform

A Base44 app is a Vite + React SPA, a TanStack Start project or an Expo native app backed by Base44's entities, functions and auth. This reference is the platform orientation the builder itself works from: concepts, file layout, authentication wiring and user invites.

Pick the reference for this app

Determine the app profile first. Call GET /api/apps/{app_id}/agent-profile (over the Base44 MCP execute_api tool, or with your Base44 CLI token); it returns the framework, app type, runtime, entitlements and the exact reference files to read. Without it, detect from the project files: src/routes/__root.* and src/routeTree.gen.ts mean TanStack Start; app/_layout.* means a native mobile (Expo) app; otherwise it is a Vite SPA.

ProfileRead
Web app, Vite SPA (the default web template)Web app, Vite SPA
Web app, TanStack StartWeb app, TanStack Start
Native mobile app (Expo, React Native)Native mobile app (Expo)

Base44 workflows

Workflows is the pipeline for trigger-driven work: a .jsonc envelope under base44/workflows/ is live once written.

Requires the Builder plan or above. The workspace's entitlement is reported by the agent-profile endpoint; on a lower plan the platform rejects the operation.

Pick the reference for this app

Determine the app profile first. Call GET /api/apps/{app_id}/agent-profile (over the Base44 MCP execute_api tool, or with your Base44 CLI token); it returns the framework, app type, runtime, entitlements and the exact reference files to read. Without it, detect from the project files: src/routes/__root.* and src/routeTree.gen.ts mean TanStack Start; app/_layout.* means a native mobile (Expo) app; otherwise it is a Vite SPA.

ProfileRead
Web app, Vite SPA (the default web template)Workflows (Vite SPA and mobile: steps call backend functions)
Web app, TanStack StartWorkflows (TanStack Start: steps call server routes)
Native mobile app (Expo, React Native)Workflows (Vite SPA and mobile: steps call backend functions)

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

// 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();
// 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.

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)
currentUserawait 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})

Exception: an OpenAI-compatible client (e.g. the Vercel AI SDK or the openai SDK) is correct when pointed at base44.asServiceRole.aiGateway.connection() — that's how you build code agents (agent loops with tools) and call the gateway's image, video, and speech endpoints. Use InvokeLLM only for a single call with no tools. See ai-gateway.md.

Actors - WRONG vs CORRECT

❌ WRONG (hallucinated)✅ CORRECT
actors.connect('ChatRoom', roomId)actors.ChatRoom(roomId).connect()
actors.ChatRoom.connect(roomId)actors.ChatRoom(roomId).connect()
actors.ChatRoom(roomId).subscribe(cb)subscribe on the connection: const conn = actors.ChatRoom(roomId).connect(); conn.subscribe(cb)
room.on('message', cb)room.subscribe(cb) (one callback receives every message)
room.emit(data)room.send(data)
new WebSocket(...) for app realtimebase44.actors.<Name>(id).connect()
const unsub = room.subscribe(cb); unsub()const sub = room.subscribe(cb); sub.unsubscribe()

The two subscribe() methods return different shapes. Connection.subscribe() (actors) returns an object — sub.unsubscribe(). entities.<Name>.subscribe() returns the unsubscribe function itself — unsub(). Don't carry one convention to the other.

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

ModulePurposeReference
entitiesCRUD operations on data modelsentities.md
authLogin, register, user managementauth.md
agentsAI conversations and messagesbase44-agents.md
functionsBackend function invocationfunctions.md
actors / asServiceRole.actorsRealtime rooms over WebSockets (multiplayer, collaboration, presence); call an actor's static callable methods without connectingactors.md
integrationsAI, email, file uploads, custom APIsintegrations.md
aiGatewayBase44's AI gateway: code agents, images, videos, speech, and structured evaluations (Jev)ai-gateway.md
payments / asServiceRole.paymentsCheckouts, purchases, refunds, and subscriptions (Stripe/PayPal/Base44 Payments)payments.md
analyticsTrack custom events and user activityanalytics.md
appLogsLog user activity in appapp-logs.md
appRead the app's own public settings (visibility)app.md
usersInvite users to the appusers.md
connectorsApp user OAuth flows (start/disconnect the current user's own connection)connectors.md
asServiceRole.connectorsShared/app-scoped OAuth tokens and metered connector calls (service role only)connectors.md
asServiceRole.ssoSSO token generation (service role only)sso.md
asServiceRole.browserRemote browser automation sessions (service role only)browser.md
asServiceRole.voiceLive voice sessions, beta (service role only)voice.md

For client setup and authentication modes, see 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, actors, and agents: The Base44 CLI generates types from your project resources (entities, functions, actors, agents), including augmentations to EntityTypeRegistry, FunctionNameRegistry, ActorNameRegistry, 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, functions.md, actors.md, and base44-agents.md. Actor message types are always hand-authored — augment ActorRegistry so the actor and its clients share one definition.

Installation

Install the Base44 SDK:

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:

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:

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 one image with default settings → integrations.Core.GenerateImage()
  • Several images, a specific model/aspect ratio/resolution, reference images, or edits → aiGateway images (see ai-gateway.md)
  • Generate a simple text-to-video → integrations.Core.GenerateVideo(); model choice, references, or frames → aiGateway videos, an async job (see ai-gateway.md)
  • Text-to-speech (TTS) or read-aloud → speech guide for browser/Core/gateway selection; read it before implementing model-specific controls or editing existing gateway speech code
  • Classify, score, or route a record against criteria → aiGateway with provider: "typesafe" (Jev), not InvokeLLM with a JSON schema (see ai-gateway.md)
  • Build a custom agent with tools (backend, agent SDK on the AI gateway) → aiGateway (see ai-gateway.md)

Custom backend logic?

  • Run server-side code → functions.invoke()
  • Need admin access → base44.asServiceRole.functions.invoke()

Realtime shared session?

  • Multiplayer, collaborative board/doc, presence, live cursors, in-room chat → actors.<Name>(roomId).connect() (see actors.md)
  • Just keeping a list of records live on screen → entities.EntityName.subscribe(), not an actor

External services?

  • Send emails (now with HTML/text/attachments) → integrations.Core.SendEmail()
  • Upload files → integrations.Core.UploadFile()
  • Custom APIs (OpenAPI-based) → integrations.custom.call()
  • Shared/app-scoped OAuth token (app builder's account) → asServiceRole.connectors.getConnection() (backend only)
  • Per-user OAuth (each app user's own account) → connectors.connectAppUser() (frontend) + asServiceRole.connectors.getCurrentAppUserConnection() (backend)
  • Metered third-party API calls (Base44 holds the credential) → asServiceRole.connectors.callApi() (backend only)
  • Remote browser automation (Playwright/Puppeteer over CDP) → asServiceRole.browser.getSession() (backend only)

Payments?

  • Accept one-time payments or subscriptions → asServiceRole.payments.createCheckout() (backend, creates it) + payments.mountCheckout() (frontend, renders it) — see payments.md
  • Look up the current user's own purchases → payments.listPurchases()
  • Refund a payment or change a subscription → asServiceRole.payments.refund() / cancelSubscription() / pauseSubscription() / resumeSubscription() (backend only)

Live voice?

  • Voice conversation between an app user and an AI agent using the app's tools → asServiceRole.voice.createSession() (backend only, beta) — see voice.md

Tracking and analytics?

  • Track custom events → analytics.track()
  • Log page views/activity → appLogs.logUserInApp()
  • Check the app's visibility / whether the visitor can access it → app.getPublicSettings()

Common Patterns

Filter and Sort Data

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

Protected Routes (check auth)

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

// Frontend
// ⚠️ invoke() returns the RAW axios response — your function's JSON is on `.data`,
//    NOT the top-level object. It also THROWS on non-2xx (error body at err.response.data).
const res = await base44.functions.invoke("processOrder", {
  orderId: "123",
  action: "ship"
});
const result = res.data; // ✅ e.g. res.data.success  (res itself is { data, status, headers, … })

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

export default async function (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 });
}

Realtime Room (Actor)

// Frontend — connect inside useEffect and always clean up
useEffect(() => {
  const room = base44.actors.ChatRoom(roomId).connect();
  const sub = room.subscribe((msg) => {
    if (msg.type === "message") setMessages((prev) => [...prev, msg]);   // switch on type; drop unknowns
  });
  return () => { sub.unsubscribe(); room.close(); };   // NOTE: actors return { unsubscribe() },
}, [roomId]);                                          // entities.subscribe() returns the function itself

// Actor — base44/actors/ChatRoom/entry.ts
import { Actor } from "base44:runtime/actors";

export default class ChatRoom extends Actor {
  handleConnect(conn) { conn.send({ type: "welcome" }); }        // one client
  handleMessage(conn, msg) {
    // Always validate: the payload is attacker-controlled and msg can even be null.
    if (msg?.type !== "message" || typeof msg.text !== "string") return;
    this.broadcast({ type: "message", text: msg.text.slice(0, 2000) });   // everyone
  }
  handleClose(conn) {}
}

Service Role Access

Use asServiceRole in backend functions for admin-level operations. Actors expose this.client.asServiceRole for validated, room-owned work such as persisting canonical results; use verified conn.identity.userId from an authenticated connection for explicit user attribution. See actors.md.

// 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

CapabilityFrontendBackend
entities (user's data)YesYes
authYesYes
agentsYesYes
functions.invoke()YesYes
functions.fetch()YesYes
actors (connect to a room)YesNo — the actor is the server side
actors (call a static callable method)Yes—
asServiceRole.actors (call a static callable method)NoYes
integrationsYesYes
aiGatewayNoYes
payments (preload/mount/complete/list own purchases)YesNo
asServiceRole.payments (create checkout/refund/subscriptions)NoYes
analyticsYesYes
appLogsYesYes
app (read public settings)YesYes
usersYesYes
connectors (app user OAuth: connect/disconnect)YesNo
asServiceRole.*NoYes
asServiceRole.connectors (shared/app OAuth, metered calls)NoYes
asServiceRole.ssoNoYes
asServiceRole.browserNoYes
asServiceRole.voice (beta)NoYes

Backend functions export default an async request handler and use createClientFromRequest(req) to get a properly authenticated client.

Troubleshoot Production Issues

Prerequisites

Verify authentication before fetching logs:

npx base44 whoami

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

Resolve app context in one of these ways:

# From a linked local project
cat base44/.app.jsonc

# Or explicitly
npx base44 logs --app-id app_123

Available Commands

CommandDescriptionReference
base44 logsFetch function logs for this appproject-logs.md
base44 workflows runsList workflow runs, newest first; failed runs carry the failing task and the underlying errorworkflows-runs.md
base44 workflows listList this app's workflows with status and run summaryworkflows-list.md

Logs are not read-after-write

A single fetch that misses your run proves nothing. One-shot base44 logs reads an index that lags behind the invocation, so an empty result right after triggering a function is the expected result, not evidence of a problem.

  • Live debugging: use --follow. Where the realtime stream is available it delivers lines in under a second. Where it is not, the CLI says so and polls instead (Warning: Realtime logs are not available for this app — falling back to polling (lines may lag ~20-30s).). Either way --follow is the right tool — you never have to pick.
  • One-shot fetches lag ~20-30s. That is ingestion time, not a filter problem.
  • When output is empty, the variable to change is TIME, never a flag. Wait and re-run the same command. Widening --limit, dropping --level, or switching --order changes nothing about a line that has not been ingested yet, and re-rolling flags is how agents talk themselves into a wrong diagnosis.

Troubleshooting Flow

1. Watch it happen — --follow

If you can trigger the failure (or it is happening now), start here rather than fetching after the fact:

npx base44 logs --follow
npx base44 logs --follow --function <function_name>

Then invoke the function and read what arrives. Rules that keep you from misreading a healthy stream:

  • Never decide on a timer. Open the stream, trigger the function, and read until you see the lines — do not read a fixed window, print, and conclude "broken". A quiet stream is quiet because nothing has been invoked.
  • Delivery is per-invocation, not per-line. A long-running function's lines all arrive when the invocation ends. Silence mid-invocation is normal.
  • Redeploying mid-follow is safe. A deploy rotates the script in seconds and the same open stream delivers the new code's lines on the next invoke. Do not tear the stream down and rebuild it after every deploy.
  • --since is rejected with --follow (the stream starts from now), as are --until and --order. For anything historical, use a one-shot fetch.
  • The mode is decided once, at startup. If the first connection is refused or unreachable, the run polls for its whole life. If the stream opens, there is no polling fallback left.
  • A stream lost mid-run ends the command with Error: The realtime log stream stopped and could not be re-established, exit code 1. That exit is the stream giving up, not proof that logging is broken — re-run the same command rather than changing flags.

2. Ask whether it was a scheduled run, not a request

Workflows are the automation system — cron schedules, entity triggers, connector events, in-app agent actions. When the complaint is "my scheduled job didn't run" or "the automation stopped working", function logs are the wrong tool. They show what a function printed; they cannot tell you whether a run was dispatched at all, which task inside it failed, or why the workflow stopped firing.

npx base44 workflows runs --status failed
npx base44 workflows list

A failed run carries the failing task and the underlying error, so start there and drop into base44 logs only once you know which function a failing task called. workflows list reports consecutiveFailures — anything above zero is a workflow that needs attention.

Two things that mislead here:

  • manual in the trigger column does not mean a person clicked something. It is what a run is stamped with when it was dispatched with no trigger type at all.
  • Test runs are included, tagged next to the trigger type as (scheduled, test). A run you fired yourself to check something will show up in the list.

3. Check Recent Errors

Start by pulling the latest errors across all functions:

npx base44 logs --level error

4. Drill Into a Specific Function

If you know which function is failing:

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

If you are outside the project directory, pass the app explicitly:

npx base44 logs --app-id app_123 --function <function_name> --level error

A --function filter is a filter on stamped rows. Apps still on the legacy per-function deployment emit unstamped rows, so a filtered view can hide them; this self-heals on the app's next deploy. If a filtered run comes back empty, re-run without --function before concluding there are no logs.

5. Inspect a Time Range

Correlate with user-reported issue timestamps:

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

6. Analyze the Logs

  • Look for stack traces and error messages in the output
  • Check timestamps to correlate with user-reported issues
  • Pass --limit explicitly to reach further back — there is no default page size, and a value above 500 is clamped down to 500

Reading an empty result

No logs found matching the filters. is ambiguous — never read it as "healthy". It means one of:

  • the run has not been ingested yet (most common — wait and re-run, see above)
  • no function by that name, or the filter dropped unstamped rows (see step 3)
  • the app has not been published, when reading --env prod (No production logs found. — try --env preview for draft logs)

Sponsors

Details

Marketplace
base44/skills
Author
base44
Category
Development
License
MIT
Keywords
base44, full-stack, sdk, cli, deployment

More from base44/skills

All 2