base44-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Base44 CLI

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

使用Base44 CLI工具创建和管理Base44应用（项目）。

⚡ 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 NO (new project scenario):
- This skill (base44-cli) handles the request
- Guide user through project initialization
- Do NOT activate base44-sdk yet
If YES (existing project scenario):
- Transfer to base44-sdk skill for implementation
- This skill only handles CLI commands (login, deploy, entities push)

只要提及“base44”或存在

base44/

文件夹，本技能就会激活。在执行操作前，请勿阅读文档文件或搜索网络。

你的首要操作必须是：

检查当前目录下是否存在
```
base44/config.jsonc
```
如果不存在（新项目场景）：
- 由本技能（base44-cli）处理请求
- 引导用户完成项目初始化
- 暂不激活base44-sdk技能
如果存在（已有项目场景）：
- 转由base44-sdk技能处理实现工作
- 本技能仅处理CLI命令（登录、部署、实体推送）

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

切勿直接调用

base44

。该CLI作为开发依赖项本地安装，必须通过包管理器访问：

```
npx base44 <command>
```
（npm - 推荐方式）
```
yarn base44 <command>
```
（yarn）
```
pnpm base44 <command>
```
（pnpm）

错误示例：

base44 login

正确示例：

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

关键事项：每当本技能被激活的AI会话启动时，你必须：

检查认证状态，运行以下命令：
bash
```
npx base44 whoami
```
如果用户已登录（命令执行成功并显示邮箱）：
- 继续执行请求的任务
如果用户未登录（命令执行失败或显示错误）：
- 立即停止操作
- 请勿继续执行任何CLI操作
- 请用户手动登录，运行以下命令：
  bash
```
npx base44 login
```
```
- 等待用户确认已登录后再继续
```

此检查为强制要求，必须在执行任何其他Base44 CLI命令之前完成。

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.

Base44 CLI提供了用于认证、创建项目、管理实体和部署Base44应用的命令行工具。它与框架无关，可与Vite、Next.js、Create React App、Svelte、Vue等主流前端框架配合使用。

When to Use This Skill vs base44-sdk

何时使用本技能 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)

使用base44-cli的场景：

从无到有创建新的Base44项目
在空目录中初始化项目
目录中缺少
```
base44/config.jsonc
```
用户提及：“创建新项目”、“初始化项目”、“设置项目”、“启动新的Base44应用”
通过CLI进行部署、推送实体或认证
使用CLI命令（
```
npx base44 ...
```
）

使用base44-sdk的场景：

在已有的Base44项目中构建功能
```
base44/config.jsonc
```
已存在
使用Base44 SDK编写JavaScript/TypeScript代码
实现功能、组件或特性
用户提及：“实现”、“构建功能”、“添加功能”、“编写代码”

技能依赖关系：

在新项目中，
```
base44-cli
```
是
```
base44-sdk
```
的前置条件
如果用户想要“创建应用”且不存在Base44项目，请先使用
```
base44-cli
```
```
base44-sdk
```
假定Base44项目已完成初始化

状态检查逻辑： 选择技能前，请检查：

如果（用户提及“创建/构建应用” 或 “创建项目”）：
- 如果（目录为空或不存在
```
base44/config.jsonc
```
  ）： → 使用base44-cli（需要项目初始化）
- 否则： → 使用base44-sdk（项目已存在，构建功能）

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
│   ├── entities/                # Entity schema definitions
│   │   ├── task.jsonc
│   │   └── board.jsonc
│   ├── functions/               # Backend functions (optional)
│   │   └── my-function/
│   │       ├── function.jsonc
│   │       └── index.ts
│   └── agents/                  # Agent configurations (optional)
│       └── support_agent.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/agents/*.jsonc
```
- Agent 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"
  "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"`
`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	-

Base44项目结合了标准前端项目和

base44/

配置文件夹：

my-app/
├── base44/                      # Base44配置目录（由CLI创建）
│   ├── config.jsonc             # 项目设置、站点配置
│   ├── entities/                # 实体模式定义
│   │   ├── task.jsonc
│   │   └── board.jsonc
│   ├── functions/               # 后端函数（可选）
│   │   └── my-function/
│   │       ├── function.jsonc
│   │       └── index.ts
│   └── agents/                  # Agent配置（可选）
│       └── support_agent.jsonc
├── src/                         # 前端源代码
│   ├── api/
│   │   └── base44Client.js      # Base44 SDK客户端
│   ├── pages/
│   ├── components/
│   └── main.jsx
├── index.html                   # SPA入口文件
├── package.json
└── vite.config.js               # 或你的框架配置文件

关键文件：

```
base44/config.jsonc
```
- 项目名称、描述、站点构建设置
```
base44/entities/*.jsonc
```
- 数据模型模式（请参阅实体模式部分）
```
base44/agents/*.jsonc
```
- Agent配置（可选）
```
src/api/base44Client.js
```
- 预配置的SDK客户端，供前端使用

config.jsonc示例：

jsonc

{
  "name": "My App",                    // 必填：项目名称
  "description": "App description",    // 可选：项目描述
  "entitiesDir": "./entities",         // 可选：默认值为"entities"
  "functionsDir": "./functions",       // 可选：默认值为"functions"
  "agentsDir": "./agents",             // 可选：默认值为"agents"
  "site": {                            // 可选：站点部署配置
    "installCommand": "npm install",   // 可选：安装依赖的命令
    "buildCommand": "npm run build",   // 可选：构建命令
    "serveCommand": "npm run dev",     // 可选：本地开发服务器命令
    "outputDirectory": "./dist"        // 可选：构建输出目录
  }
}

配置属性说明：

属性	描述	默认值
`name`	项目名称（必填）	-
`description`	项目描述	-
`entitiesDir`	实体模式文件所在目录	`"entities"`
`functionsDir`	后端函数所在目录	`"functions"`
`agentsDir`	Agent配置文件所在目录	`"agents"`
`site.installCommand`	安装依赖的命令	-
`site.buildCommand`	项目构建命令	-
`site.serveCommand`	启动本地开发服务器的命令	-
`site.outputDirectory`	部署用的构建输出目录	-

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.

在你的项目中安装Base44 CLI作为开发依赖：

bash

npm install --save-dev base44

重要提示： 切勿假定或硬编码

base44

包的版本。请始终不带版本标识符进行安装，以获取最新版本。

然后使用

npx

运行命令：

bash

npx base44 <command>

注意： 本文档中的所有命令均使用

npx base44

。你也可以根据偏好使用

yarn base44

或

pnpm base44

。

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

命令	描述	参考文档
`base44 login`	使用设备代码流进行Base44认证	auth-login.md
`base44 logout`	从当前设备登出	auth-logout.md
`base44 whoami`	显示当前已认证用户	auth-whoami.md

Project Management

项目管理

Command	Description	Reference
`base44 create`	Create a new Base44 project from a template	create.md ⚠️ MUST READ
`base44 link`	Link an existing local project to Base44	link.md
`base44 dashboard`	Open the app dashboard in your browser	dashboard.md

命令	描述	参考文档
`base44 create`	从模板创建新的Base44项目	create.md ⚠️ 必须阅读
`base44 link`	将现有本地项目关联到Base44	link.md
`base44 dashboard`	在浏览器中打开应用控制台	dashboard.md

Deployment

部署

Command	Description	Reference
`base44 deploy`	Deploy all resources (entities, functions, site)	deploy.md

命令	描述	参考文档
`base44 deploy`	部署所有资源（实体、函数、站点）	deploy.md

Entity Management

实体管理

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

操作 / 命令	描述	参考文档
创建实体	在 `base44/entities` 文件夹中定义实体	entities-create.md
`base44 entities push`	将本地实体推送至Base44	entities-push.md
RLS模式	行级安全示例及运算符	rls-examples.md ⚠️ 使用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.

创建实体文件时，请严格遵循以下结构：

文件命名规则：

base44/entities/{短横线分隔名称}.jsonc

（例如，

team-member.jsonc

对应

TeamMember

实体）

模式模板：

jsonc

{
  "name": "EntityName",
  "type": "object",
  "properties": {
    "field_name": {
      "type": "string",
      "description": "字段描述"
    }
  },
  "required": ["field_name"]
}

字段类型：

string

number

integer

boolean

array

object

binary

字符串格式：

date

date-time

time

email

uri

hostname

ipv4

ipv6

uuid

file

regex

richtext

枚举类型： 添加

"enum": ["value1", "value2"]

，可选择性添加

"default": "value1"

实体名称规则： 只能包含字母和数字（匹配正则：

/^[a-zA-Z0-9]+$/

）

完整文档请参阅entities-create.md。

Function Management

函数管理

Action / Command	Description	Reference
Create Functions	Define functions in `base44/functions` folder	functions-create.md
`base44 functions deploy`	Deploy local functions to Base44	functions-deploy.md

操作 / 命令	描述	参考文档
创建函数	在 `base44/functions` 文件夹中定义函数	functions-create.md
`base44 functions deploy`	将本地函数部署至Base44	functions-deploy.md

Agent Management

Agent管理

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
`base44 agents push`	Push local agents to Base44	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是可与用户交互、访问应用实体并调用后端函数的对话式AI助手。使用以下命令管理Agent配置。

操作 / 命令	描述	参考文档
创建Agent	在 `base44/agents` 文件夹中定义Agent	请参阅下方的Agent模式
`base44 agents pull`	将远程Agent拉取到本地文件	agents-pull.md
`base44 agents push`	将本地Agent推送至Base44	agents-push.md

注意： Agent命令执行全量同步 - 推送操作会用本地Agent覆盖所有远程Agent，拉取操作会用远程Agent覆盖所有本地Agent。

Agent Schema (Quick Reference)

Agent模式（快速参考）

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

文件命名规则：

base44/agents/{agent名称}.jsonc

（例如，

support_agent.jsonc

）

模式模板：

jsonc

{
  "name": "agent_name",
  "description": "该Agent功能的简要描述",
  "instructions": "Agent行为的详细说明",
  "tool_configs": [
    // 实体工具 - 赋予Agent访问实体操作的权限
    { "entity_name": "tasks", "allowed_operations": ["read", "create", "update", "delete"] },
    // 后端函数工具 - 赋予Agent调用函数的权限
    { "function_name": "send_email", "description": "发送邮件通知" }
  ],
  "whatsapp_greeting": "你好！我能为你提供什么帮助？"
}

命名规则：

Agent名称必须匹配正则：
```
/^[a-z0-9_]+$/
```
（小写字母、数字和下划线，长度1-100字符）
有效示例：
```
support_agent
```
,
```
order_bot
```
无效示例：
```
Support-Agent
```
,
```
OrderBot
```

必填字段：

name

description

instructions

可选字段：

tool_configs

（默认值为

[]

）,

whatsapp_greeting

工具配置类型：

实体工具：

entity_name

allowed_operations

（可选值数组：

read

create

update

delete

）

后端函数工具：
```
function_name
```
+
```
description
```

Site Deployment

站点部署

Command	Description	Reference
`base44 site deploy`	Deploy built site files to Base44 hosting	site-deploy.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).

命令	描述	参考文档
`base44 site deploy`	将构建好的站点文件部署到Base44托管服务	site-deploy.md

仅支持SPA：Base44托管服务仅支持单页应用（Single Page Applications），要求有单个

index.html

入口文件。所有路由均从

index.html

提供服务（客户端路由）。

Quick Start

快速开始

Install the CLI in your project:
bash
```
npm install --save-dev base44
```
Authenticate with Base44:
bash
```
npx base44 login
```
Create a new project (ALWAYS provide name and
```
--path
```
flag):
bash
```
npx base44 create my-app -p .
```
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 agents push
```
- Push agents only
```
npx base44 site deploy -y
```
- Deploy site only

在项目中安装CLI：
bash
```
npm install --save-dev base44
```
进行Base44认证：
bash
```
npx base44 login
```
创建新项目（必须提供名称和
```
--path
```
参数）：
bash
```
npx base44 create my-app -p .
```
构建并部署所有资源：
bash
```
npm run build
npx base44 deploy -y
```

也可以单独部署各类资源：

```
npx base44 entities push
```
- 仅推送实体
```
npx base44 functions deploy
```
- 仅部署函数
```
npx base44 agents push
```
- 仅推送Agent
```
npx base44 site deploy -y
```
- 仅部署站点

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.

⚠️ 强制要求： 在运行

base44 create

前，你必须阅读create.md以了解：

模板选择 - 选择正确的模板（
```
backend-and-client
```
vs
```
backend-only
```
）
正确工作流 - 不同模板需要不同的设置步骤
常见陷阱 - 避免导致项目脚手架失败的文件夹创建错误

不遵循create.md中的说明会导致项目脚手架损坏。

Linking an Existing Project

关联现有项目

bash

undefined

bash

undefined

If you have base44/config.jsonc but no .app.jsonc

如果你有base44/config.jsonc但没有.app.jsonc

npx base44 link --create --name my-app

undefined

npx base44 link --create --name my-app

undefined

Deploying All Changes

部署所有变更

bash

undefined

bash

undefined

Build your project first

先构建你的项目

npm run build

Deploy everything (entities, functions, and site)

部署所有资源（实体、函数和站点）

npx base44 deploy -y

undefined

npx base44 deploy -y

undefined

Deploying Individual Resources

单独部署资源

bash

undefined

bash

undefined

Push only entities

仅推送实体

npx base44 entities push

Deploy only functions

仅部署函数

npx base44 functions deploy

Push only agents

仅推送Agent

npx base44 agents push

Deploy only site

仅部署站点

npx base44 site deploy -y

undefined

npx base44 site deploy -y

undefined

Opening the Dashboard

打开控制台

bash

undefined

bash

undefined

Open app dashboard in browser

在浏览器中打开应用控制台

npx base44 dashboard

undefined

npx base44 dashboard

undefined

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.

大多数命令需要认证。如果未登录，CLI会自动提示你登录。会话信息会存储在本地，并在CLI会话间保持有效。

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

错误	解决方案
未认证	先运行 `npx base44 login`
未找到实体	确保实体文件存在于 `base44/entities/` 目录
实体未被识别	确保文件使用短横线分隔命名（例如 `team-member.jsonc` 而非 `TeamMember.jsonc` ）
未找到函数	确保函数文件存在于 `base44/functions/` 目录且包含有效的 `function.jsonc` 配置
未找到Agent	确保Agent配置文件存在于 `base44/agents/` 目录且为有效的 `.jsonc` 格式
Agent名称无效	Agent名称只能包含小写字母、数字和下划线
未找到站点配置	检查项目配置中是否已设置 `site.outputDirectory`
站点部署失败	确保你已先运行 `npm run build` 且构建成功