AgileBuilder logoAgileBuilder
返回文档

安装 AgileBuilder

安装 AgileBuilder CLI 的环境要求、安装方式、验证、升级与卸载说明

环境要求

安装 AgileBuilder CLI 之前，请确认你的系统满足以下条件：

  • Node.js 20.0.0 或更高版本（CLI 的 engines 字段要求 node >= 20.0.0）
  • Git：模板以 Git 仓库形式分发，创建项目时需要 Git 可用
  • 任意包管理器：npm（Node.js 自带）、pnpm 或 yarn 均可

检查环境：

node --version   # 需要 >= v20.0.0
git --version

安装 CLI

通过 npm 全局安装：

npm install -g agilebuilder

安装完成后会提供三个可执行命令：

命令说明
agilebuilderCLI 主命令
agagilebuilder 的短别名，二者完全等价
agilebuilder-mcpMCP stdio server，供 AI 工具配置调用

也可以不安装、直接通过 npx 运行（适合 CI 或临时使用）：

npx agilebuilder --help
npx agilebuilder@latest create --git-url <url> --target ./app

验证安装

ag --version    # 输出版本号，例如 1.2.2
ag --help       # 查看全部命令

ag --help 应能看到这些命令：config、login、logout、auth、space、res、create、device。

选择后端区域

CLI 通过 backend.profile 配置项决定连接哪个区域的云端服务：

值行为
auto（默认）根据系统语言/时区自动判断：中国大陆环境使用中国区，否则使用全球区
china使用 *.agilebuilder.cn 端点
global使用 *.agilebuilder.net 端点
ag config list                          # 查看当前配置
ag config set backend.profile global    # 手动指定区域
ag config set language zh-CN            # CLI 输出语言：auto / zh-CN / en-US

只使用本地功能（不登录云端）时无需关心区域设置。

数据目录

CLI 的本地数据默认存放在：

~/.agilebuilder/v2

主要文件：

文件用途
config.jsonCLI 配置
current-space.json当前选中的工作空间
resources/local.json本地模板与文档资源
auth.enc加密保存的登录凭据

可以通过环境变量 AGILEBUILDER_CORE1_DATA_DIR 覆盖数据目录：

AGILEBUILDER_CORE1_DATA_DIR=/tmp/ag-data ag res list

升级与卸载

升级到最新版本：

npm install -g agilebuilder@latest

卸载：

npm uninstall -g agilebuilder

卸载不会删除 ~/.agilebuilder/v2 数据目录。如需彻底清理，请手动删除该目录。

下一步