AgileBuilder CLI 是一个基于 Git 模板的项目脚手架与开发资源管理工具。安装后提供 agilebuilder 命令（短别名 ag，两者完全等价），以及 agilebuilder-mcp MCP 服务进程。

包名：agilebuilder
运行环境：Node.js >=20.0.0

npm install -g agilebuilder

无需安装也可以直接运行（适合 CI 与 AI 智能体）：

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

全局用法

agilebuilder [options] [command]
ag [options] [command]

选项	说明
`-V, --version`	输出版本号。
`-h, --help`	显示帮助。
`help [command]`	显示指定命令的帮助。

命令总览

命令	说明
`config`	管理 CLI 配置。
`login`	使用 OAuth 或 API Key 登录。
`logout`	清除本地认证。
`auth status`	显示认证状态。
`auth require-token`	要求当前存在可用 token，否则以非零退出码失败。
`space list` / `space ls`	列出本地和 Cloud 工作空间。
`space current`	显示当前工作空间。
`space use <workspace>`	选择 `local` 或 Cloud 工作空间 ID。
`res list` / `res ls`	列出资源。
`res search <keyword>`	搜索资源。
`res get <id>`	查看资源详情。
`res add template`	添加模板资源。
`res add doc`	添加文档资源。
`res edit <id>`	编辑资源。
`res remove <id>` / `res rm <id>`	删除资源。
`create [resource-id]`	从资源或 Git URL 创建项目。
`device list` / `device ls`	列出已注册设备。
`device revoke <device-id>`	撤销单个设备。
`device revoke-all`	撤销除当前设备之外的所有设备。

res 也可以写作 resource。资源的完整使用方式见资源管理。

config：CLI 配置

ag config list
ag config get backend.profile
ag config set backend.profile global

支持的配置项（其他键会被拒绝）：

配置项	可用值	默认值	说明
`backend.profile`	`auto`、`china`、`global`	`auto`	后端端点选择。`china` 使用 `.agilebuilder.cn`（`www`、`api-auth`、`api-app`），`global` 使用 `.agilebuilder.net`。`auto` 在 locale 或时区显示为中国大陆环境时使用中国区，否则使用全球区。
`language`	`auto`、`zh-CN`、`en-US`	`auto`	CLI 输出语言。为 `auto` 时依次读取 `AGILEBUILDER_LANG`、`LC_ALL`、`LC_MESSAGES`、`LANG`。
`template.allowHooksDefault`	`true`、`false`	`false`	`create` 未传入 `--allow-hooks` 时的默认 Hook 授权行为。显式传入 `--allow-hooks` 始终优先级最高。

config set 的值会按标量解析：true/false 解析为布尔值，数字解析为数值，其余保留为字符串。

Cloud 资源、Cloud 工作空间、许可证刷新和设备管理都需要登录。

OAuth 登录（默认方式）：

ag login

CLI 会打开浏览器，并在 127.0.0.1 监听 OAuth 回调。默认从端口 51280 开始，最多向后探测 10 个端口；全部占用时报 OAUTH_PORT_UNAVAILABLE。

API Key 登录：

ag login --api-key <key>

查看与清除认证状态：

ag auth status          # 显示登录状态、认证方式与用户信息
ag auth require-token   # 无可用 token 时以 AUTH_TOKEN_UNAVAILABLE 失败，适合脚本前置检查
ag logout               # 清除本地保存的认证数据

三者都支持 --json。OAuth token 会在可行时自动刷新；API Key 会作为当前凭据保存，直到执行 logout。

space：工作空间

AgileBuilder 包含一个内置的本地工作空间（local，无需登录），登录后还可以使用 AgileBuilder Cloud 工作空间。当前工作空间会影响资源命令和 create <resource-id> 的资源解析。

ag space list            # 列出本地与 Cloud 工作空间（支持 --refresh 刷新云端缓存、--json）
ag space current         # 显示当前工作空间
ag space use local       # 切回本地工作空间
ag space use <space-id>  # 切换到 Cloud 工作空间

资源写入命令默认作用于当前工作空间，也可以用 --space-id <id> 临时指定目标工作空间，而不切换当前工作空间。

res：资源管理

资源分两类：template（Git 仓库指针，用于 create）和 doc（Markdown / 纯文本文档）。以下只列语法，完整实战见资源管理。

ag res list [--type template|doc] [--space-id <id>] [--json]
ag res search <keyword> [--type template|doc] [--space-id <id>] [--json]
ag res get <id> [--json]

--space-id 可指定操作的 Cloud 工作空间（list/search 与 add/edit/remove 均支持）；本地工作空间是扁平列表，不支持目录树，--parent-id 仅 Cloud 可用。

添加模板资源（--name、--git-url 必填，--branch 默认 main）：

ag res add template \
  --name service-template \
  --git-url https://github.com/example/service-template.git \
  --branch main \
  --subdir templates/node \
  --description "Node.js service starter" \
  --tags "node,service"

添加文档资源（--file 与 --content 至少提供一个）：

ag res add doc \
  --name architecture-notes \
  --file ./docs/architecture.md \
  --format markdown \
  --tags "docs,architecture"

文档资源选项：--uri <uri>（本地文档默认 local-doc://<name>）、--format <format>（markdown 或 text，默认 markdown）。

编辑与删除：

ag res edit <id> --name new-name --description "Updated"
ag res edit <doc-id> --file ./README.md --format markdown
ag res remove <id> --yes

编辑校验规则：至少传入一个可编辑字段；--file 与 --content 不能同时使用；模板专属字段（--git-url、--branch、--subdir）不能用于文档资源，文档专属字段（--uri、--file、--content、--format）不能用于模板资源。删除必须显式传入 --yes。

create：创建项目

从 Git URL 直接创建，或从当前工作空间中的模板资源创建：

ag create --git-url https://github.com/example/template.git --target ./app
ag create <resource-id> --target ./app

选项：

选项	是否必填	说明
`[resource-id]`	使用 `--git-url` 时不需要	必须指向模板资源，指向文档资源会报 `CREATE_REQUIRES_TEMPLATE`。
`--git-url <url>`	使用资源 ID 时不需要	直接从 Git 仓库创建（浅克隆，`--depth 1`）。
`--branch <branch>`	否	覆盖资源分支，或指定直接 Git 克隆的分支。
`--subdir <path>`	否	覆盖资源子目录，或指定仓库内模板子目录。
`--target <dir>`	是	输出目录。
`--vars <path>`	否	包含单个 JSON 对象的变量文件。
`--var <key=value...>`	否	一个或多个标量变量赋值。
`--overwrite`	否	允许写入非空目标目录。
`--keep-git`	否	保留模板仓库的 `.git` 目录；默认跳过 `.git`。
`--allow-hooks`	否	允许执行模板 Hook，优先级高于 `template.allowHooksDefault`。
`--interactive`	否	交互式录入缺失的模板变量。需要在 TTY 中运行，不能与 `--json` 同时使用。
`--json`	否	输出 JSON。

变量优先级（--vars 文件 > --var 参数；其余未提供的变量先取模板配置中的默认值，仍缺失的再通过交互录入补充）：

--vars <path> 文件中的变量。
重复传入的 --var key=value（覆盖 --vars 中的同名变量）。
模板问题（inquirerQuestions）中的默认值，仅在变量仍缺失时应用。
--interactive 交互录入，仅补充仍缺失的变量。

--var 会将 true、false、null 和数字解析为对应标量类型，其他值保留为字符串。

目标目录安全规则：

CLI 拒绝写入系统目录（如盘符根目录、C:\Windows、C:\Program Files 等），违规报 UNSAFE_TARGET_DIR。
已存在且非空的目录必须显式传入 --overwrite，否则报 TARGET_NOT_EMPTY。
目标目录不存在时自动创建。

device：设备管理

设备命令需要登录：

ag device list                                  # 列出已注册设备
ag device revoke <device-id> --reason "No longer used"
ag device revoke-all                            # 撤销除当前设备之外的所有设备

均支持 --json。

JSON 输出协议

所有标注“支持 --json”的命令遵循同一套结构化输出协议，适合脚本与 AI 智能体消费。

成功时输出到 stdout：

{
  "ok": true,
  "data": {}
}

失败时输出到 stderr，进程以退出码 1 结束：

{
  "ok": false,
  "error": {
    "code": "TEMPLATE_VARS_MISSING",
    "message": "Missing required template variables: appName",
    "suggestion": "Pass values with --vars or --var key=value, or use --interactive to enter them interactively.",
    "category": "validation"
  }
}

error.category 取值：auth、permission、network、validation、resource、system。suggestion 字段给出可执行的修复建议，这是为 AI 智能体设计的关键字段。未传入 --json 时，错误以可读文本输出。

常见错误码

错误码	含义与建议
`CREATE_SOURCE_REQUIRED`	未提供资源 ID 或 `--git-url`。
`CREATE_REQUIRES_TEMPLATE`	`create` 的资源 ID 指向了文档资源。
`TEMPLATE_VARS_MISSING`	缺少必填模板变量，用 `--var` / `--vars` / `--interactive` 补齐。
`TEMPLATE_VARS_FILE_INVALID`	`--vars` 文件不存在、不可读或不是单个 JSON 对象。
`TEMPLATE_VAR_INVALID`	`--var` 赋值格式错误，应为 `key=value`。
`TEMPLATE_CONFIG_INVALID`	模板配置文件不是合法 YAML/JSON。
`TEMPLATE_SUBDIR_UNSAFE`	`--subdir` 为绝对路径或包含 `..`，逃逸出模板目录。
`UNSAFE_TARGET_DIR`	目标目录是系统目录或盘符根目录。
`TARGET_NOT_EMPTY`	目标目录非空且未传 `--overwrite`。
`TARGET_NOT_WRITABLE`	目标路径已存在且不是目录。
`HOOK_TYPE_UNSUPPORTED`	Hook 的 `scriptType` 不是 `shell`。
`HOOK_FAILED`	Hook 执行失败且 `errorHandling` 为 `stop`。
`HOOK_TIMEOUT`	Hook 执行超过 5 分钟超时。
`INTERACTIVE_JSON_CONFLICT`	`--interactive` 与 `--json` 不能同时使用。
`INTERACTIVE_NOT_TTY`	`--interactive` 需要在 TTY 中运行。
`RESOURCE_NOT_FOUND`	资源 ID 不存在。
`RESOURCE_EDIT_FIELD_REQUIRED`	`res edit` 未传入任何可编辑字段。
`RESOURCE_EDIT_CONTENT_CONFLICT`	`--file` 与 `--content` 不能同时使用。
`RESOURCE_EDIT_TYPE_MISMATCH`	编辑字段与资源类型不匹配。
`UNSUPPORTED_RESOURCE_TYPE`	资源类型不是 `template` 或 `doc`。
`LOCAL_WORKSPACE_UNSUPPORTED_OPTION`	`--parent-id` 等选项仅 Cloud 工作空间支持。
`CONFIRMATION_REQUIRED`	`res remove` 缺少 `--yes`。
`DOC_CONTENT_REQUIRED`	添加文档资源时 `--file` 与 `--content` 均未提供。
`DOC_FILE_READ_FAILED`	`--file` 指向的文件不可读。
`AUTH_TOKEN_UNAVAILABLE`	未登录或 token 不可用，先执行 `ag login`。
`API_KEY_REQUIRED`	`--api-key` 传入了空值。
`OAUTH_PORT_UNAVAILABLE`	OAuth 回调端口 51280 起连续 10 个端口均被占用。
`OAUTH_TIMEOUT`	OAuth 登录等待回调超时。
`WORKSPACE_NOT_FOUND`	工作空间 ID 不存在，登录后用 `ag space list --refresh` 刷新。
`CONFIG_KEY_REQUIRED`	`config get` 缺少键名。
`UNEXPECTED_ERROR`	未预期错误，请携带 `--json` 输出反馈。

数据目录与环境变量

默认数据目录：

~/.agilebuilder/v2

文件	用途
`config.json`	CLI 配置（见 `config` 命令）。
`current-space.json`	当前选中的工作空间 ID。
`resources/local.json`	本地模板资源和文档资源。
`auth.enc`	加密保存的认证数据。
`license-cache.json`	许可证与 Cloud 工作空间列表缓存。

环境变量	说明
`AGILEBUILDER_CORE1_DATA_DIR`	覆盖数据目录，适合 CI 隔离与测试。
`AGILEBUILDER_LANG`	覆盖 CLI 输出语言（`language` 为 `auto` 时优先于 `LC_ALL` 等）。

AGILEBUILDER_CORE1_DATA_DIR=/tmp/agilebuilder-core ag res list

MCP 服务模式

包中附带 MCP stdio server，命令为 agilebuilder-mcp，可被支持 MCP 协议的 AI IDE 调用，用于查询资源、读取文档上下文并创建项目脚手架。配置方式与工具列表见 MCP 集成。

已知限制

当前只支持执行 after_write 的 shell Hook，详见文件匹配与 Hooks。
本地资源是扁平列表，不支持目录。
Cloud 操作依赖 AgileBuilder 后端 API 的可用性和当前用户权限。