base44-cli

Base44 CLI

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

⚡ 需要立即采取行动——请先阅读

提及“base44”或存在 base44/ 文件夹时，此技能都会激活。请勿在采取行动前阅读文档文件或搜索网络。

你必须首先执行以下操作：

1. 检查当前目录中是否存在 base44/config.jsonc
2. 如果存在（现有项目场景）：
   • 转交给 base44-sdk 技能进行实现
   • 此技能仅处理 CLI 命令（登录、部署、推送实体）
   • 但在本地运行应用除外——仍由此技能处理。在启动开发服务器前，请阅读运行本地开发：其中一种运行方式会访问生产数据。
3. 如果不存在，请在以下两种初始化路径中做出选择：
   • 已配置的应用——Base44 应用已通过 Stripe Projects / projects.dev 流程配置完成，或者环境中或 .env/.env.local 文件中存在 BASE44_APP_ID（或 BASE44_PROJECTS_BASE44_APP_ID）：
     • 运行 npx base44 scaffold，为该现有应用设置本地文件
     • 请勿运行 npx base44 create——这会创建第二个重复的应用。请参阅 scaffold.md。
   • 新项目——尚无应用，也未配置任何应用：
     • 此技能（base44-cli）负责处理请求；引导用户运行 npx base44 create
     • 暂不激活 base44-sdk

重要：仅限本地安装

绝不要直接调用 base44。CLI 作为开发依赖安装在本地，必须通过包管理器访问：

• npx base44 <command>（npm，推荐）
• yarn base44 <command>（yarn）
• pnpm base44 <command>（pnpm）

错误：base44 login 正确：npx base44 login

必须：会话开始时进行身份验证检查

重要：每次激活此技能时，在 AI 会话开始之初，必须：

1. 检查身份验证状态，运行：

   npx base44 whoami
   

2. 如果用户已登录（命令成功执行并显示电子邮件地址）：

   • 继续执行请求的任务

3. 如果用户未登录（命令执行失败或显示错误）：

   • 立即停止
   • 不要继续执行任何 CLI 操作
   • 请用户手动登录，运行：

     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 配置（由 CLI 创建）
│   ├── config.jsonc             # 项目设置、站点配置
│   ├── .types/                  # 自动生成的 TypeScript 类型（由 `types generate` 创建）
│   │   └── types.d.ts           # 对 @base44/sdk 的模块扩充
│   ├── entities/                # 实体架构定义
│   │   ├── task.jsonc
│   │   └── board.jsonc
│   ├── functions/               # 后端函数（可选）
│   │   └── my-function/
│   │       └── entry.ts
│   ├── actors/                  # 实时 Actor（可选）
│   │   └── ChatRoom/
│   │       └── entry.ts
│   ├── agents/                  # Agent 配置（可选）
│   │   └── support_agent.jsonc
│   ├── agent-skills/            # Agent 技能说明（可选）
│   │   └── pdf-export.md
│   └── connectors/              # OAuth 连接器配置（可选）
│       └── googlecalendar.jsonc
├── src/                         # 前端源代码
│   ├── api/
│   │   └── base44Client.js      # Base44 SDK 客户端
│   ├── pages/
│   ├── components/
│   └── main.jsx
├── index.html                   # SPA 入口点
├── package.json
└── vite.config.js               # 或你的框架配置

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

配置属性：

属性	说明	默认值
name	项目名称（必填）	-
description	项目说明	-
visibility	应用可见性：public、private 或 workspace	-
entitiesDir	实体架构目录	"entities"
functionsDir	后端函数目录	"functions"
actorsDir	实时 Actor 目录	"actors"
agentsDir	Agent 配置目录	"agents"
agentSkillsDir	Agent 技能说明目录	"agent-skills"
connectorsDir	连接器配置目录	"connectors"
site.installCommand	安装依赖项的命令	-
site.buildCommand	构建项目的命令	-
site.serveCommand	运行开发服务器的命令	-
site.outputDirectory	部署用的构建输出目录	-

安装

在项目中将 Base44 CLI 安装为开发依赖项：

npm install --save-dev base44

**重要：**切勿假设或硬编码 base44 软件包版本。始终不指定版本号进行安装，以获取最新版本。

然后使用 npx 运行命令：

npx base44 <command>

**注意：**本文档中的所有命令都使用 npx base44。你也可以根据需要使用 yarn base44 或 pnpm base44。

全局 --app-id 选项

CLI 提供全局 --app-id <id> 选项，适用于只需要应用上下文、不需要本地项目文件的命令。

解析顺序：--app-id 标志 → BASE44_APP_ID 环境变量 → 本地 base44/.app.jsonc

如果你想在不切换到已关联的项目目录的情况下检查或操作应用，此选项会很有用。常见示例：

# 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

对于 exec 和 logs 等应用范围内的命令，请使用 --app-id。

对于需要本地项目文件的命令，不要使用 --app-id：

• base44 create 会创建一个新应用，因此不接受 --app-id
• base44 dev 会在已关联的本地项目中运行，因此不接受 --app-id
• base44 deploy 仍需要本地项目目录，因为它会读取本地资源

全局 --json 选项

CLI 提供全局 --json 选项，可让命令在标准输出中输出机器可读的 JSON 文档，而非面向人类的内容。它还会强制启用非交互模式（旋转指示器／状态消息／日志会转到标准错误），确保标准输出中只有纯 JSON，便于安全地通过管道传给 jq 或其他程序。

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

可用命令

身份验证

命令	描述	参考
base44 login	使用设备代码流程通过 Base44 进行身份验证	auth-login.md
base44 logout	退出当前设备的登录状态	auth-logout.md
base44 whoami	显示当前已通过身份验证的用户	auth-whoami.md

项目管理

命令	描述	参考
base44 create	根据模板创建新的 Base44 项目	create.md ⚠️ MUST READ
base44 scaffold	为现有 Base44 应用（通过应用 ID 指定）搭建本地项目	scaffold.md
base44 link	将现有本地项目关联到 Base44	link.md
base44 eject	下载现有 Base44 项目的代码	eject.md
base44 dashboard open	在浏览器中打开应用仪表板	dashboard.md
base44 visibility <level>	设置应用在服务端的可见性（public、private 或 workspace）	visibility.md

工作区管理

工作区（又称组织）通过共享成员资格将应用归组。默认情况下，base44 create／base44 link --create 使用你的个人工作区；传入 -w, --workspace <id> 可指定其他工作区。

命令	描述	参考
base44 workspace list	列出你所属的工作区	workspace-list.md
base44 workspace get <workspace-id>	按 ID 显示单个工作区的详细信息	workspace-get.md
base44 workspace move [workspace-id]	将当前应用移至其他工作区	workspace-move.md

开发

命令	描述	参考
base44 dev	启动 Base44 后端的本地开发；若配置了 site.serveCommand，也会启动前端	dev.md
base44 dev --remote	在本地提供前端服务，并连接到生产后端	dev.md

部署

命令	描述	参考
base44 build	构建网站并注入其应用 ID；请用它代替直接运行 npm run build	—
base44 deploy	部署所有资源（实体、函数、演员、Agent、Agent 技能、连接器、身份验证配置和网站）；会询问是否先构建，也可传入 --build／--no-build	deploy.md

实体管理

操作／命令	描述	参考
创建实体	在 base44/entities 文件夹中定义实体	entities-create.md
base44 entities push	将本地实体推送到 Base44	entities-push.md
RLS 模式	行级安全示例和运算符	rls-examples.md ⚠️ READ FOR RLS

实体 Schema（快速参考）

创建实体文件时，始终遵循以下精确结构：

文件命名： base44/entities/{kebab-case-name}.jsonc（例如，TeamMember 对应 team-member.jsonc）

Schema 模板：

{
  "name": "EntityName",
  "type": "object",
  "properties": {
    "field_name": {
      "type": "string",
      "description": "Field 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。

函数管理

操作 / 命令	描述	参考
创建函数	在 base44/functions 中定义函数	functions-create.md
base44 functions deploy [names...] [--force]	将本地函数部署到 Base44；可指定目标函数，也可清理已移除的函数	functions-deploy.md
base44 functions delete <names...>	从 Base44 删除一个或多个已部署的函数	functions-delete.md
base44 functions list	列出 Base44 远程服务上的所有已部署函数	functions-list.md
base44 functions pull [name]	将已部署的函数从 Base44 拉取到本地文件	functions-pull.md

工作流运行

工作流是自动化系统（定时计划、实体触发器、连接器事件、应用内 Agent 操作）。这些命令为只读命令：用于回答“有哪些工作流”以及“我的定时任务是否失败，原因是什么”。

命令	描述	参考
base44 workflows list	列出此应用的工作流及其状态和运行摘要	workflows-list.md
base44 workflows runs [--status <s>] [--since <t>]	按时间从新到旧列出工作流运行记录；失败的运行记录会包含底层错误	workflows-runs.md

Actor 管理

Actor 是基于 WebSocket 的有状态实时服务端房间——每个房间 ID 对应一个运行实例，并由所有连接到该 ID 的客户端共享。可将其用于多人游戏会话、协作白板、在线状态和实时光标、房间内聊天以及实时拍卖。

Actor 使用由 SDK 管理身份验证的直接连接。使用经过验证的 conn.identity 确定用户归属，并使用 this.client.asServiceRole 持久化经过验证的房间结果。Actor 不会接收任何应用密钥；依赖密钥的操作应放在后端函数中。有关编写规范，请参阅 actors-create.md。

操作 / 命令	描述	参考
创建 Actor	在 base44/actors 中定义 Actor	actors-create.md
base44 actors deploy [names...]	将本地 Actor 部署到 Base44；可指定目标 Actor	actors-deploy.md
base44 actors delete <names...>	拆除已部署的 Actor（销毁已发布的脚本）	actors-deploy.md

Actor 布局（快速参考）

文件命名： base44/actors/{ActorName}/entry.ts——文件夹就是 Actor 的身份。

// 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) {}
}

命名规则： Actor 名称会成为 JavaScript 类绑定和 WebSocket 连接处理程序——必须匹配 [A-Za-z_][A-Za-z0-9_]*（最多 128 个字符，不能包含 /、-、. 或 :），不能是 JS 保留字，不能与后端函数名称冲突，也不能嵌套在子文件夹中。CLI 会在上传前于本地检查所有这些规则；名称中带点的文件夹会被跳过（因此 ChatRoom.bak/ 可用作安全的临时目录）。

• 有效：ChatRoom、BoardRoom、Lobby
• 无效：chat-room、games/Arena、class

必需： entry.ts（或 entry.js），其中要默认导出一个继承自 base44:runtime/actors 中 Actor 的类。使用 TypeScript 时，还要声明 handleTick() {}——它是 Actor 的抽象成员。

与函数的区别： 只会上传 Actor 自己的文件夹（不包含 base44/shared/）；没有 --force 清理功能，没有 list/pull 命令，没有本地 base44 dev 运行时；名称不能类似路径，也不支持自动化。

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

Agent 管理

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 架构（快速参考）

文件命名： base44/agents/{agent_name}.jsonc（例如 support_agent.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" },
    // 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?"
}

命名规则：

• Agent 名称必须符合以下模式：/^[a-z0-9_]+$/（小写字母、数字和下划线，1–100 个字符）
• 有效：support_agent、order_bot
• 无效：Support-Agent、OrderBot

必需字段： name、description、instructions 可选字段： tool_configs（默认为 []）、memory_config、whatsapp_greeting

工具配置类型：

• 实体工具： entity_name + allowed_operations（数组，可选值：read、create、update、delete）
• 后端函数工具： function_name + description
• 服务端路由工具（全栈应用）：tool_name（1–64 个字母、数字、_ 或 -）+ route_path（相对于应用的路径，以单个 / 开头，不含查询字符串）+ method（get|post|put|patch|delete，默认为 post）+ description（默认为 "agent server route"）

记忆配置字段（均为可选，详情请参阅 agents-push.md）：enabled（布尔值，默认为 true）、scope（global|user|both，默认为 both）、include_other_conversation_context（布尔值，默认为 false）、instructions（字符串|null，默认为 null）

Agent 技能管理

Agent 技能是可复用的 Markdown 指令，可扩展应用中的 AI Agent 能执行的任务。使用以下命令进行管理。

操作 / 命令	描述	参考
创建 Agent 技能	在 base44/agent-skills 文件夹中定义技能	agent-skills-push.md
base44 agent-skills pull	将远程 Agent 技能拉取到本地文件	agent-skills-pull.md
base44 agent-skills push	将本地 Agent 技能推送到 Base44	agent-skills-push.md

注意： Agent 技能命令会执行完整同步——推送会用本地技能替换所有远程技能，拉取会用远程技能替换所有本地技能。

Agent 技能架构（快速参考）

文件命名： base44/agent-skills/{skill-name}.md（例如：pdf-export.md）

架构模板：

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

命名规则： 技能名称（去掉 .md 的文件名）必须符合模式 /^[a-z0-9]+(-[a-z0-9]+)*$/（小写字母、以连字符分隔，长度为 1–64 个字符）

• 有效：pdf-export、order-lookup
• 无效：PdfExport、pdf_export

必填字段： description（frontmatter，1–1024 个字符）、正文（Markdown 内容，1–15000 个字符）

完整文档请参阅 agent-skills-push.md。

连接器管理

连接器可让应用连接到外部服务（Google Calendar、Slack、Stripe 等）。大多数连接器使用 OAuth 为后端函数提供访问令牌，以便调用外部 API。Stripe 是个例外——它在服务端自动配置，无需经过 OAuth 浏览器流程。

操作 / 命令	描述	参考
创建连接器	在 base44/connectors 文件夹中定义连接器	connectors-create.md
base44 connectors list-available	列出 Base44 提供的所有可用集成类型	connectors-list-available.md
base44 connectors initiate --integration-type <t> [--scopes <s...>]	初始化连接器并启动其 OAuth 流程；使用 --app-id 时，无需项目即可运行	connectors-initiate.md
base44 connectors pull	将远程连接器拉取到本地文件	connectors-pull.md
base44 connectors push	将本地连接器推送到 Base44	connectors-push.md

注意： 连接器命令会执行完整同步——推送会用本地连接器替换所有远程连接器（并为新的 OAuth 连接器启动 OAuth 流程），拉取会用远程连接器替换所有本地连接器。

连接器架构（快速参考）

文件命名： base44/connectors/{type}.jsonc（例如，googlecalendar.jsonc、slack.jsonc）

架构模板：

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

必填字段： type 可选字段： scopes（默认为 []）

可用连接器类型： 运行 npx base44 connectors list-available 查看所有受支持的集成类型。

注意： stripe 也是有效的连接器类型，但不会由 list-available 返回。请将其视为受支持的类型——Base44 会自动配置它，无需 OAuth 浏览器流程。详情请参阅 connectors-create.md。

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

身份验证配置

管理应用的身份验证设置（例如，用户名和密码登录）。身份验证配置存储在 base44/auth/ 中，并通过 auth push/auth pull 与 Base44 同步。

命令	说明	参考
base44 auth password-login <enable|disable>	启用或停用用户名和密码身份验证	auth-password-login.md
base44 auth social-login <provider> <enable|disable>	启用或停用社交登录（google、microsoft、facebook、apple）	auth-social-login.md
base44 auth sso <enable|disable>	配置 SSO 身份提供方（google、microsoft、github、okta、custom）	auth-sso.md
base44 auth pull	将 Base44 中的身份验证配置拉取到本地文件	auth-pull.md
base44 auth push	将本地身份验证配置推送到 Base44	auth-push.md

注意： 身份验证配置也会作为 base44 deploy 的一部分进行部署。

密钥管理

管理项目密钥（安全存储在 Base44 中的环境变量）。这些命令不会显示在 --help 输出中，但都可以正常使用。

命令	说明	参考
base44 secrets list	列出所有密钥的名称	secrets-list.md
base44 secrets set	设置一个或多个密钥（KEY=VALUE 或 --env-file）	secrets-set.md
base44 secrets delete <key>	按名称删除密钥	secrets-delete.md

脚本执行

使用预先完成身份验证的 Base44 SDK，针对应用运行一次性脚本。可用于对实体执行 CRUD 操作（base44.entities.MyEntity.list/create/update/delete）、调用后端函数（base44.functions.invoke("myFunction", args)）、调用 Agent，或访问 SDK 提供的其他任何资源——无需部署完整函数。适用于数据迁移、批量操作、调试和脚本化工作流。

命令	说明	参考
base44 exec	使用预先完成身份验证的 Base44 SDK 运行脚本（通过 stdin）	exec.md

类型生成

命令	说明	参考
base44 types generate	根据实体、函数、角色、Agent 和连接器生成 TypeScript 类型（types.d.ts）	types-generate.md

输出： base44/.types/types.d.ts——为 @base44/sdk 模块扩充带类型的注册表（EntityTypeRegistry、FunctionNameRegistry、AgentNameRegistry、ConnectorTypeRegistry、ActorNameRegistry）。

无需身份验证。 完全在本地运行，并自动更新 tsconfig.json 以包含生成的类型。

站点管理

命令	描述	参考
base44 site deploy	将构建后的站点文件部署到 Base44 托管服务	site-deploy.md
base44 site open	在浏览器中打开已部署的站点	site-open.md

仅限 SPA：Base44 托管服务支持使用单个 index.html 入口点的单页应用。所有路由均由 index.html 提供（客户端路由）。

其他 API 操作

对于没有对应专用命令的 Base44 平台任务（自定义域名、URL 重定向、SEO 设置、应用用户、协作者和所有权、分析、安全扫描、工作区成员和群组、CSV 导入等），请使用 base44 api 直接查找并调用公共 API 端点。它通过服务器的 OpenAPI 规范，使用你的 CLI 登录凭据，涵盖 Apps API 和 Workspace API。

仅当专用命令能完全满足请求时，才优先使用它（base44 secrets、base44 functions、base44 logs、base44 deploy 以及本技能中的其他命令）。如果它还会执行用户未要求的操作（请先阅读其参考文档），则改用 base44 api。

API 涵盖应用和工作区，不涵盖你自己的 Base44 账户：没有用于操作密码、电子邮件或个人资料的接口。此类操作请引导用户前往 Base44 Web 应用。

操作流程：

1. **查找端点：**运行 npx base44 api search "<what you want to do>"，或通过 api catalog [area] 浏览，或者在搜索无结果时使用 api grep <regex>。每个结果中的 endpoint（例如 "GET /api/apps/{app_id}/custom-domains"）就是要原样传入的方法和路径。
2. **阅读接口约定：**运行 npx base44 api fetch <METHOD> <path> --help | jq '.description, .parameters, .requestBodySchema, .responseSchema'。调用前先阅读 description：搜索结果中的首个操作不一定合适。
3. **调用接口：**运行 npx base44 api fetch <METHOD> <path> [--body <json>]。仅查看时添加 --read-only。

命令	描述	参考
base44 api search <text...>	根据功能搜索所有公共 API 操作	api-search.md
base44 api catalog [area]	列出 API 的所有区域，或某个区域中的所有操作	api-catalog.md
base44 api grep <pattern>	使用正则表达式搜索 API 规范，适用于搜索无结果时	api-grep.md
base44 api fetch <METHOD> <path>	使用你的登录凭据调用操作；在路径后添加 --help 查看其接口约定	api-fetch.md ⚠️ 调用前必读

快速开始

1. 在项目中安装 CLI：

   npm install --save-dev base44
   

2. 使用 Base44 进行身份验证：

   npx base44 login
   

3. 创建新项目（必须提供名称和 --path 标志）：

   npx base44 create my-app --path .
   

4. 运行本地开发：

   npx base44 dev
   

5. 构建并部署所有内容：

   npx base44 deploy --build -y
   

或者单独部署各类资源：

• npx base44 entities push - 仅推送实体
• npx base44 functions deploy - 仅部署函数
• npx base44 functions delete <name> - 删除已部署的函数
• npx base44 functions list - 列出所有已部署的函数
• npx base44 functions pull - 将已部署的函数拉取到本地文件
• npx base44 actors deploy - 仅部署实时 Actor
• npx base44 actors delete <name> - 拆除已部署的 Actor
• npx base44 agents push - 仅推送 Agent
• npx base44 agent-skills push - 仅推送 Agent 技能
• npx base44 connectors pull - 从 Base44 拉取连接器
• npx base44 connectors push - 仅推送连接器
• npx base44 auth pull - 从 Base44 拉取身份验证配置
• npx base44 auth push - 仅推送身份验证配置
• npx base44 site deploy -y - 仅部署站点

常见工作流

创建新项目

⚠️ 必须：运行 base44 create 前，必须阅读 create.md，了解：

• 模板选择——选择正确的模板（backend-and-client 或 backend-only）
• 正确的工作流——不同模板需要不同的设置步骤
• 常见问题——避免导致失败的文件夹创建错误

如果未遵循 create.md 中的说明，项目脚手架将无法正常工作。

链接现有项目

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

运行本地开发

始终通过 CLI 运行——有两种模式：

命令	后端 + 数据
npx base44 dev	本地——临时环境，每次启动时为空，停止后即消失
npx base44 dev --remote	生产环境——真实应用的实时数据

base44 dev 会启动本地后端（实体、函数、身份验证），并在 base44/config.jsonc 设置了 site.serveCommand 时提供前端服务；仅后端项目无需其他设置。 --remote 仅使用真实后端运行前端，因此需要已链接的项目和 site.serveCommand。

不要自行运行 npm run dev：如果没有 CLI 注入的环境变量，应用将无法连接后端——开发服务器会打印应使用的命令。

默认使用 npx base44 dev。 使用 --remote 时，所有写入操作都会影响线上应用。无论使用哪种模式，Vite 启动信息都会显示后端：[base44] Proxy enabled: /api -> <target>。请说明你启动了哪种模式。选项见：dev.md。

部署所有更改

# 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

使用 CLI 进行构建，不要运行 npm run build：npx base44 build 会注入 VITE_BASE44_APP_ID，而直接运行 npm run build 不会设置该变量——这样生成的构建包便无法解析自身的应用，部署后网站的所有 API 调用都会失败。npx base44 deploy 会询问是否先进行构建；使用 --build / --no-build 可提前指定（非交互模式下默认仅上传，因此 CI 不会改变）。

生成 TypeScript 类型

# Generate types from entities, functions, actors, agents, and connectors
npx base44 types generate

这会创建 base44/.types/types.d.ts，其中包含 @base44/sdk 模块的类型化注册表。更改实体、函数、参与者、Agent 或连接器后，请运行此命令以保持类型同步。无需身份验证。

部署单个资源

# 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

打开控制面板

# Open app dashboard in browser
npx base44 dashboard

身份验证

大多数命令都需要身份验证。如果你尚未登录，CLI 会自动提示你登录。会话会保存在本地，并在 CLI 会话之间持续有效。

故障排查

错误	解决方案
未通过身份验证	先运行 npx base44 login
未找到实体	确保 base44/entities/ 目录中存在实体
无法识别实体	确保文件使用 kebab-case 命名（例如，使用 team-member.jsonc，而不是 TeamMember.jsonc）
未找到函数	确保 base44/functions/ 中存在函数，且包含 entry.ts 或 entry.js
未找到 Actor	确保 Actor 位于 base44/actors/<ActorName>/entry.ts（绝不能直接放在 base44/actors/ 中）
Actor 名称无效	Actor 名称必须匹配 [A-Za-z_][A-Za-z0-9_]*（不能包含 /、-、. 或 :），避免使用 JS 保留字，且不能嵌套。在任何上传之前，本地就会捕获此问题
actors cannot be nested	将文件移至 base44/actors/<ActorName>/entry.ts，或者重命名名为 entry.ts 的辅助文件——base44/actors/ 下的每个 entry 文件都会被视为 Actor
Actor 和函数同名	它们会部署到同一命名空间——请重命名其中一个
函数存储桶拒绝 Actor 文件	导入 base44:runtime/actors 的文件必须位于 base44/actors/<ActorName>/entry.ts——将其移出 base44/functions/
未找到 Agent	确保 base44/agents/ 目录中存在 Agent，且包含有效的 .jsonc 配置
Agent 名称无效	Agent 名称只能使用小写字母数字字符和下划线
未找到 Agent 技能	确保 base44/agent-skills/ 目录中存在技能文件，且文件为有效的 .md 文件
技能文件无效	技能文件名必须使用小写字母和连字符，且其 frontmatter 中必须包含 description
推送已取消／需要 --yes	agents push、agent-skills push、entities push 和 connectors push 都会执行破坏性全量同步——请交互式确认，或在 CI／非交互模式下传入 -y／--yes
未找到连接器	确保 base44/connectors/ 目录中存在连接器，且包含有效的 .jsonc 配置
连接器类型无效	运行 npx base44 connectors list-available 查看有效类型
连接器类型重复	每个项目中只能定义一次每种连接器类型
连接器授权超时	重新运行 npx base44 connectors push，并在浏览器中完成 OAuth 流程
未找到站点配置	检查项目配置中是否配置了 site.outputDirectory
站点部署失败	确保先构建站点（运行 npx base44 build 或 npx base44 deploy --build），且构建成功
部署后站点的所有 API 调用均失败	构建包时未包含应用 ID——请使用 npx base44 build 重新构建，而不是直接运行 npm run build，然后重新部署
有可用更新提示	如果系统提示更新，请运行 npm install -g base44@latest（本地安装时也可使用 npx）