CLI
aidy 是每个 aidy 宿主的命令行,也是宿主编写目录时的工具。需要 Node 22 或更高版本。
npm install -g @aidy-dev/cli使用教程见 CLI 指南。
Usage: aidy [--host <url>] [--yes] <command> [args]全局参数写在命令之前。
| 参数 | 含义 |
|---|---|
--host <url>、--host=<url> |
使用的宿主。必须是 http 或 https URL,末尾的斜杠会被去掉。 |
--yes、-y |
不询问,直接确认写操作。 |
--help、-h |
打印用法。aidy help 效果相同。写在命令之后时打印该命令的帮助。 |
| 变量 | 含义 |
|---|---|
AIDY_HOST |
未给出 --host 时使用的宿主。 |
AIDY_TOKEN |
token。设置了 AIDY_HOST 时只发给该宿主,否则发给实际使用的宿主;从不写入磁盘,也从不打印。 |
品牌 CLI 读取自己的变量名,默认为 <NAME>_HOST 和 <NAME>_TOKEN(见 brand)。
宿主依次取 --host、AIDY_HOST、最近一次 aidy login 登录的宿主、品牌 CLI 的预设宿主。token 取 AIDY_TOKEN,否则取 login 为该宿主保存的 token。没有宿主时,aidy 以退出码 3 退出,并提示 no host; pass --host <url>, set AIDY_HOST, or run aidy login <url>。
宿主命令用上面得到的 token 连接 <host>/mcp(MCP streamable HTTP,bearer token)。
内置命令为 login、logout、status、tools 和 search。宿主命令的第一个词与它们同名时,以宿主命令为准;aidy:<name> 总是运行内置命令(aidy aidy:login),编写命令也可以这样调用(aidy:skill)。每个命令都支持 --help(-h)。
aidy login [host-url] [--token-stdin]保存宿主的 token,并设为本程序的默认宿主。不加 --token-stdin 时,aidy 在终端上询问 token 且不回显;没有终端时必须使用 --token-stdin。它从不读取 AIDY_TOKEN。login 会连接宿主并列出工具来检验 token,然后打印 {"host", "tools"}。宿主依次取自参数、--host、AIDY_HOST。
logout
Section titled “logout”aidy logout [host-url]删除该宿主的 token 及其缓存的工具列表。不带参数时登出 --host 指定的宿主,否则登出默认宿主。
status
Section titled “status”打印宿主、所用的凭据(login 或 token 变量名)、MCP 服务端的名称和版本,以及你可用的工具数量。从不打印 token:
{ "host": "https://console.example.com", "credential": "AIDY_TOKEN", "server": { "name": "…", "version": "…" }, "tools": 42 }status 取代了 whoami。
aidy tools [--json]列出宿主为你提供的全部命令,每行一个,附带摘要和作用。--json 输出 [{command, tool, args, effect?, description}]。
search
Section titled “search”aidy search "gpu box"在 aidy 宿主上,它调用宿主的 search 工具:对产品的搜索操作和知识库做联合搜索。内置的 search(宿主没有该工具时,或以 aidy:search 调用时)列出名称、命令词或说明中包含查询所有词的命令。
宿主工具命令
Section titled “宿主工具命令”aidy <command words> [positionals] [--flags]aidy <command words> --help命令不是内置的。aidy 列出宿主的 MCP 工具,并按每个工具 _meta.aidy 中的单词拼出命令:
{ "name": "stop_vm", "_meta": { "aidy": { "command": "vm stop", "args": ["vm_id"], "effect": "update" } } }没有 _meta.aidy 的工具成为单个命令,即工具名中的 _ 换成 -,没有位置参数。匹配时取最长的命令。命令写法来自 x-aidy.cli。
| 输入 | 写法 |
|---|---|
| 位置参数 | 工具的 args,按顺序。 |
| 其他属性 | --page-size 20:_ 换成 -。也可以写成 --name=value。 |
| 布尔值 | --flag、--no-flag,或 --flag=true/--flag=false。 |
| 数组 | 重复参数:--tag a --tag b。 |
| 对象 | JSON 对象:--labels '{"team":"ml"}'。 |
| 数字 | 会校验:整数必须是整数值。 |
| 整体输入 | --input-json <file|->:从文件或 stdin 读取 JSON 对象,参数会覆盖其中的键。 |
| 参数结束 | --:其后全部视为位置参数。 |
| 确认 | --yes、-y(除非工具本身有 yes 属性)。 |
| 帮助 | --help、-h:用法、描述、全部参数,写操作还会列出 -y。 |
缺少必填输入时,在发送任何请求之前以退出码 2 失败。
写操作。 宿主通过 MCP elicitation 请求确认。在终端上,aidy 显示问题并等待输入 y;--yes 直接接受;没有终端时拒绝,并提示传入 --yes。
输出。 打印工具的结构化内容;没有时,把唯一的文本内容按 JSON 解析后打印。输出为 stdout 上的 JSON:终端上格式化,否则为单行。工具错误以 error: … 打印到 stderr,退出码为 1。
--openapi 接受 JSON 文件或 http(s) URL。-o/--out 写入文件;不加时输出到 stdout。编写命令拒绝未知参数,退出码为 2;--help 打印该命令的用法。
aidy check --openapi <file|url> [--routes routes.txt]以 <位置>: <信息> 打印所有目录问题,有问题时以 1 退出;否则向 stderr 打印 ok: N operations。--routes 是 UI 发出的 METHOD /path 请求列表,每行一个。没有目录操作对应的路由会报错,除非标注了 # browser-only: <原因>:
GET /api/vmsPOST /api/vm/{vm_id}/stopGET /api/session/ping # browser-only: keepalive for the UI见 校验失败。
aidy skill --openapi <file|url> --product <name> --url <url> [--guide guide.md] [--cli-command acme] [-o SKILL.md]生成 agent skill:frontmatter、手写的指南、连接方式(MCP 地址 <url>/mcp,给出 --cli-command 时还有 CLI)、安全规则和操作索引。
aidy llms --openapi <file|url> --product <name> --url <url> --summary <text> [-o llms.txt]按 llmstxt.org 生成 llms.txt。
reference
Section titled “reference”aidy reference --openapi <file|url> [-o reference.md]生成全部操作的 Markdown 参考。
aidy docs --openapi <file|url> --product <name> --url <url> --summary <text> [--guide f] [--cli-command c] -o <dir>在目录中写入 SKILL.md、llms.txt 和 reference.md,并以 JSON 打印它们的路径。
keys generate
Section titled “keys generate”aidy keys generate --kid aidy-2026-11 [-o aidy-2026-11.private.jwk]生成一对 Ed25519 密钥。在 stdout 打印公钥 JWK(写入宿主配置),把私钥 JWK(aidy 的签名密钥)写入一个权限为 0600 的新文件,默认为 <kid>.private.jwk。不会覆盖已有文件,也从不打印私钥。两者都是可移植的:{kty, crv, x, kid} 和 {kty, crv, x, d, kid},不含 alg、key_ops 或 ext,Node、Bun、Deno 和 workerd 都能导入。见 委托。
aidy brand --name acme [--host https://console.example.com] [--env-host VAR] [--env-token VAR] -o acme-cli [--npm-name @acme/cli]生成一个小型 npm 包(package.json、bin/acme.js、README.md),其 bin acme 以 acme 的名义运行 aidy。--name 必须是小写的命令名;--npm-name 默认为 <name>-cli。
| 参数 | 含义 |
|---|---|
--host <url> |
可选的预设宿主,在没有 --host、环境变量或已保存的登录指定宿主时使用。自托管的产品不要设置。 |
--env-host VAR、--env-token VAR |
CLI 读取的环境变量。默认为 <NAME>_HOST 和 <NAME>_TOKEN:名称转大写,- 换成 _(acme → ACME_HOST、ACME_TOKEN)。 |
| 路径 | 内容 |
|---|---|
~/.config/aidy/hosts.json |
login 按宿主保存的 token,以及每个程序的默认宿主。文件权限 0600,目录 0700。token 从不打印;来自环境变量的 token 从不保存。 |
~/.cache/aidy/tools/<hash>.json |
按宿主和 token(取哈希)缓存五分钟的工具列表。login 和 status 总会刷新它。 |
XDG_CONFIG_HOME 和 XDG_CACHE_HOME 可以改变这两个目录的位置。
| 退出码 | 含义 |
|---|---|
0 |
成功。 |
1 |
工具错误:工具返回错误、JSON-RPC 错误,或 check 发现问题。 |
2 |
用法错误:未知的命令或参数,缺少值或值无效。 |
3 |
认证错误:没有宿主、未登录,或宿主返回 401 或 403。 |
4 |
网络错误:无法连接宿主,或宿主返回其他 HTTP 错误。 |
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' },});run(argv, {program?, host?, env?, io?}) 返回退出码。program 是帮助信息中显示的命令名,也是记录默认宿主的键;host 是预设宿主;env 指定宿主和 token 的环境变量名(默认为 <PROGRAM>_HOST、<PROGRAM>_TOKEN)。