跳转到内容

CLI 与品牌化

aidy 是所有 aidy 宿主通用的命令行工具。它没有内置任何宿主命令:它连接 <host>/mcp,列出当前登录用户可用的工具,并把每个工具变成一条命令。同一个程序还能为宿主生成文档和密钥。需要 Node 22 或更高版本。

终端窗口
npm install -g @aidy-dev/cli
终端窗口
aidy login https://console.example.com # asks for the token; or --token-stdin < token.txt
aidy tools # every command the host offers you
aidy vm stop gpu-train-01 --forced # a host command
aidy vm stop --help # its flags
aidy search "gpu box"
aidy status # host, credential, server, tool count
aidy logout
  • 内置命令为 login、logout、status、tools 和 search。宿主命令的第一个词与它们同名时,以宿主命令为准;aidy:<name> 总是运行内置命令(aidy aidy:login,编写命令同样可用,如 aidy:skill)。
  • 每个命令都支持 --help(-h),包括内置命令和编写命令。
  • 工具列表按宿主和令牌缓存在 ~/.cache/aidy,有效期五分钟。
宿主 令牌
1 --host <url> AIDY_TOKEN
2 AIDY_HOST login 为该宿主保存的令牌
3 最近一次 aidy login 登录的宿主
4 品牌 CLI 预设的宿主(如果有)

命令行参数优先于环境变量,环境变量优先于已保存的登录。在 CI 中设置这两个变量即可,不必 login:

终端窗口
AIDY_HOST=https://console.example.com AIDY_TOKEN=… aidy vm list # no login, nothing on disk
  • login 把读到的令牌(终端输入,或 --token-stdin)按宿主保存在 ~/.config/aidy/hosts.json(权限 0600),默认宿主按程序分别记录,因此 aidy 和各个品牌 CLI 有各自的默认宿主。
  • 来自环境变量的令牌从不写入磁盘:login 不读取它,工具缓存以哈希为键。设置了 AIDY_HOST 时,AIDY_TOKEN 只发给该宿主;用 --host 指定其他宿主时使用该宿主已保存的登录。
  • 任何命令、错误或帮助都不会打印令牌。status 会说明用的是哪种凭据:"credential": "AIDY_TOKEN" 或 "login"。
  • 位置参数依次对应工具的 args。其余输入属性都是选项:--page-size 20(_ 变为 -);布尔值用 --flag / --no-flag;数组重复同一选项;对象传 JSON;--input-json file|- 传入完整输入(单独的选项会覆盖其中的值)。
  • 结果以 JSON 输出到 stdout,在终端中会格式化显示;错误输出到 stderr。

写操作通过 MCP elicitation 请求确认。在终端中,aidy 会显示确认问题;--yes(-y)直接同意。没有终端时,除非传了 --yes,确认一律被拒绝,因此脚本必须显式同意。每次调用宿主仍会按用户自身的权限检查。

退出码 含义
0 成功
1 工具错误
2 用法错误
3 认证失败
4 网络错误

默认情况下,一个操作对应一条命令:把 name 中的 _ 换成 -,没有位置参数(stop_vm → aidy stop-vm --vm-id vm-42)。x-aidy.cli 可以为它指定命令词和位置参数:

"x-aidy": {
"name": "stop_vm",
"cli": { "command": "vm stop", "args": ["vm_id"] }
}

这样命令就变成 aidy vm stop vm-42。如果 vm_id 配置了 resolve,aidy vm stop gpu-train-01 也能用。

命令写法通过每个 MCP 工具上的 _meta.aidy 传给 CLI:

{ "name": "stop_vm", "_meta": { "aidy": { "command": "vm stop", "args": ["vm_id"], "effect": "update" } } }

@aidy-dev/documents 中的 toolMeta(op) 根据目录操作生成它。没有 _meta.aidy 的工具会成为一条以工具名命名的命令。

CLI 只能看到 surfaces 包含 cli 的操作,而所有 effect 默认都包含它。详见操作。

这些命令作用于 OpenAPI 文件或 URL(--openapi),不需要登录宿主。

终端窗口
aidy check --openapi openapi.json --routes routes.txt
aidy skill --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \
--guide guide.md --cli-command acme -o SKILL.md
aidy llms --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \
--summary "Cloud servers on demand." -o llms.txt
aidy reference --openapi openapi.json -o reference.md
aidy docs --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \
--summary "Cloud servers on demand." -o docs/
aidy keys generate --kid aidy-2026-11 -o aidy-2026-11.private.jwk
  • check 打印所有目录问题,有问题时以 1 退出。--routes 列出界面发出的请求,每行一个 METHOD /path;没有目录操作覆盖的路由会报错,除非标注了 # browser-only: <reason>。把它放进 CI,保证智能体能做的事与界面一致。
  • skill、llms、reference 和 docs 生成的文档与 aidy 在 /skill.md、/llms.txt 提供的内容相同,以文件形式放进仓库或文档站。
  • keys generate 打印公钥 JWK(给宿主配置),并把私钥 JWK(aidy 的签名密钥)写入一个新的 0600 文件。两者都是可移植的(kty、crv、x、d、kid,不含 alg),Node、Bun、Deno 和 workerd 都能导入。@aidy-dev/server 的 aidy-server keys <kid> 也能生成密钥对,但会把两部分都以 JSON 打印到 stdout。见部署。

aidy brand 生成一个小型 npm 包,它的可执行文件以你的产品命名运行 aidy:

终端窗口
aidy brand --name acme --host https://console.example.com -o acme-cli --npm-name @acme/cli
cd acme-cli && npm publish --access public
  • --host <url> 可选:预设宿主,在没有 --host、环境变量或 acme login <url> 指定宿主时使用。自托管的产品没有唯一的宿主:省略它,由用户运行 acme login https://acme.example.com 或设置宿主变量。
  • --env-host VAR 和 --env-token VAR 指定 CLI 读取的环境变量,默认为 <NAME>_HOST 和 <NAME>_TOKEN,即名称转大写、- 换成 _(acme → ACME_HOST、ACME_TOKEN);通用的 aidy 也遵循同样的规则。产品已有自己的变量时可以沿用:
终端窗口
aidy brand --name acahti --env-host ACAHTI_ROOT_URL --env-token ACAHTI_TOKEN -o acahti-cli

用户随后这样使用:

终端窗口
npm install -g @acme/cli
acme login
acme vm stop gpu-train-01

acme vm stop gpu-train-01 的效果与 aidy --host https://console.example.com vm stop gpu-train-01 相同,只是帮助和错误信息中显示 acme,并使用自己的环境变量和默认宿主。--npm-name 默认为 <name>-cli。这个包依赖 @aidy-dev/cli,aidy 的新版本通过普通的依赖更新即可获得。命令在运行时从宿主读取,新增操作无需重新发布。

要在自己的程序中内嵌 CLI,调用这个库:

import { run } from '@aidy-dev/cli';
process.exitCode = await run(process.argv.slice(2), {
program: 'acme',
host: 'https://console.example.com', // optional preset
env: { host: 'ACME_HOST', token: 'ACME_TOKEN' }, // the defaults for acme
});

所有命令和选项见 CLI 参考。