CLI 与品牌化
aidy 是所有 aidy 宿主通用的命令行工具。它没有内置任何宿主命令:它连接 <host>/mcp,列出当前登录用户可用的工具,并把每个工具变成一条命令。同一个程序还能为宿主生成文档和密钥。需要 Node 22 或更高版本。
npm install -g @aidy-dev/cliaidy login https://console.example.com # asks for the token; or --token-stdin < token.txtaidy tools # every command the host offers youaidy vm stop gpu-train-01 --forced # a host commandaidy vm stop --help # its flagsaidy search "gpu box"aidy status # host, credential, server, tool countaidy 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 disklogin把读到的令牌(终端输入,或--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。
写操作与确认
Section titled “写操作与确认”写操作通过 MCP elicitation 请求确认。在终端中,aidy 会显示确认问题;--yes(-y)直接同意。没有终端时,除非传了 --yes,确认一律被拒绝,因此脚本必须显式同意。每次调用宿主仍会按用户自身的权限检查。
| 退出码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 工具错误 |
| 2 | 用法错误 |
| 3 | 认证失败 |
| 4 | 网络错误 |
用 x-aidy.cli 定制命令
Section titled “用 x-aidy.cli 定制命令”默认情况下,一个操作对应一条命令:把 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.txtaidy skill --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \ --guide guide.md --cli-command acme -o SKILL.mdaidy llms --openapi openapi.json --product "Acme Cloud" --url https://console.example.com \ --summary "Cloud servers on demand." -o llms.txtaidy reference --openapi openapi.json -o reference.mdaidy 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.jwkcheck打印所有目录问题,有问题时以 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。见部署。
发布品牌 CLI
Section titled “发布品牌 CLI”aidy brand 生成一个小型 npm 包,它的可执行文件以你的产品命名运行 aidy:
aidy brand --name acme --host https://console.example.com -o acme-cli --npm-name @acme/clicd 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/cliacme loginacme vm stop gpu-train-01acme 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 参考。