base44-cli

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.1.7"}} 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: Check if base44/config.jsonc exists in the current directory 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. 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: Check authentication status by running: npx base44 whoami If the user is logged in (command succeeds and shows an email): Continue with the requested task 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 │ ├── 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/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" "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: Property Description Default name Project name (required) - description Project description - visibility App visibility: public , private , or workspace - entitiesDir Directory for entity schemas "entities" functionsDir Directory for backend functions "functions" agentsDir Directory for agent configs "agents" agentSkillsDir Directory for agent skill instructions "agent-skills" connectorsDir Directory for connector configs "connectors" site.installCommand Command to install dependencies - site.buildCommand Command to build the project - site.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: 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 Command Description Reference base44 login Authenticate with Base44 using device code flow auth-login.md base44 logout Logout from current device auth-logout.md base44 whoami Display current authenticated user auth-whoami.md Project Management Command Description Reference base44 create Create a new Base44 project from a template create.md ⚠️ MUST READ base44 scaffold Scaffold a local project for an existing Base44 app (by app ID) scaffold.md base44 link Link an existing local project to Base44 link.md base44 eject Download the code for an existing Base44 project eject.md base44 dashboard open Open the app dashboard in your browser dashboard.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. Command Description Reference base44 workspace list List the workspaces you belong to workspace-list.md base44 workspace get <workspace-id> Show details for a single workspace by ID workspace-get.md base44 workspace move [workspace-id] Move the current app to another workspace workspace-move.md Development Command Description Reference base44 dev Start local development for your Base44 backend, and your frontend too when site.serveCommand is configured dev.md base44 dev --remote Serve the frontend locally against the production backend dev.md Deployment Command Description Reference base44 build Build the site with its app id injected — use instead of a bare npm run build —