Echolot命令行工具
安装 echolot 命令，并了解所有命令共有的内容：机密、环境变量和退出码。
echolot 让你在终端或 CI 任务中运行在 App 里构建的内容：发送请求，运行带检查的工作区并写出报告，导入和导出集合，对规范做 Lint，提供模拟服务器，运行流程，
并通过 MCP 向 AI 智能体提供工作区。它读取与 App 相同的工作区文件，所以无需转换任何内容。
获取命令行工具
直接下载版将该工具内置在 App 中。要把它放到你的 PATH 上：
- 选取 Echolot › 安装命令行工具…，或打开设置 › 通用，在命令行工具下点按安装命令行工具…。
- Echolot 会在
/opt/homebrew/bin或/usr/local/bin中放置一个指向 App 内工具的echolot链接。如果这两个文件夹都不可写，macOS 会请你输入管理员密码。 - 打开一个新的“终端”窗口，输入
echolot --help。
设置 › 通用 › 命令行工具会显示内置工具的位置以及你 PATH 上的链接。移动 App 之后请使用重新安装，要去掉链接则使用移除。
如果有一个名为 echolot 但并非由 Echolot 放置的文件挡住了位置，Echolot 会在替换它之前询问，该文件会被移到废纸篓。
由于链接指向 App 内部，该工具会随 App 一起更新。
Mac App Store 版
App Store 版内没有该工具，也没有安装命令行工具… 项。请改用发行版页面上 zip 中的工具安装。它适用于同样的工作区。
比较两个版本命令行工具永不过期，在 App 的 Beta 版中也是如此。它需要 macOS 15 或更高版本的 Mac。
命令
| 命令 | 作用 |
|---|---|
echolot send | 发送一个请求（URL 或存储的请求文件），并将正文写入标准输出。 |
echolot run | 运行工作区、其中的部分文件夹或请求，或一个 Postman 集合，带检查和报告。 |
echolot validate | 检查工作区的每个文件都能读取、每个请求都能解析。 |
echolot import、echolot export | 将集合导入工作区，并将工作区写出为 Postman、Insomnia、Bruno 或 Echolot 格式。 |
echolot mcp | 检查 MCP 服务器、登录它们、向智能体提供工作区并打印客户端设置。 |
echolot spec | 对 OpenAPI 文档做 Lint，并检查规范更改、将其应用到跟随规范的文件夹。 |
echolot graphql diff | 比较两个 GraphQL Schema，并为每处更改评级。 |
echolot grpc | 描述 gRPC 服务并调用它们的方法。 |
echolot mqtt | 订阅 MQTT Broker 并向其发布。 |
echolot mock | 提供模拟服务器：工作区模拟服务器的路由，或一个 OpenAPI 文档。 |
echolot fake | 根据模板生成示例数据，用于测试固件和种子数据。 |
echolot flow | 列出、运行、创建和提供工作区的流程。 |
echolot agent | 让内置智能体执行一项任务，用策略代替批准。 |
echolot help <command> 和 echolot <command> --help 会打印命令的所有选项。带有子命令的命令也用同样的方式：echolot mcp serve --help。
每个命令都有的选项
| 选项 | 含义 |
|---|---|
--version | 打印版本和构建号，例如 0.5.0 (8)。 |
-h、--help | 打印该命令的选项。 |
工作区和环境
操作工作区的命令接受它的文件夹，即其中有 workspace.toml 的那个文件夹。有的命令将它作为参数（echolot run Alpenglow.echolot），
有的则用 -w 或 --workspace（echolot flow list -w Alpenglow.echolot）；每个命令的页面都会说明。可选时，使用当前文件夹。
--env 用不带 .toml 的文件名（staging）选取环境。run、validate 和 flow 也接受环境的名称（Staging）。没有 --env 时，
请求使用工作区自己的变量解析。参见环境。
机密
机密值从不存放在工作区文件中：文件只写出机密变量的名称，别无其他。命令行工具按以下顺序查找每个值：
- 环境变量
ECHOLOT_SECRET_<NAME>。名称是变量名的大写形式，其中每个不是字母或数字的字符都变为_：token对应ECHOLOT_SECRET_TOKEN，me_password对应ECHOLOT_SECRET_ME_PASSWORD。 - 对于
echolot run，用--secrets给出的文件：每行一个NAME=value，用#写注释，值两边的引号会被去掉。NAME是变量的名称（token=…） 或完整的环境变量名称（ECHOLOT_SECRET_TOKEN=…）。文件中的值优先于环境变量。 - 在 Mac 上，是 App 保存的钥匙串项目。你在 App 中设置的机密，或你登录过的 MCP 服务器，在“终端”中同样可用。
export ECHOLOT_SECRET_PASSWORD="$(op read 'op://Shop/Alpenglow staging/password')"
echolot run Alpenglow.echolot --env staging设置了 CI（值不是空、0 或 false）或 ECHOLOT_KEYCHAIN=0 时，从不使用钥匙串。这样可以避免 CI 任务卡在钥匙串的提示上。参见机密。
环境变量
| 变量 | 使用它的命令 | 含义 |
|---|---|---|
ECHOLOT_SECRET_<NAME> | 每个解析请求的命令 | 机密变量 <NAME> 的值。 |
ECHOLOT_KEYCHAIN=0 | 每个命令 | 不读取或写入钥匙串。 |
CI | 每个命令 | 设置后，钥匙串关闭，效果与 ECHOLOT_KEYCHAIN=0 相同。 |
HTTPS_PROXY、HTTP_PROXY、ALL_PROXY、NO_PROXY | send、run、mqtt 等 | 代理，读取方式与 curl 相同。--proxy 和 --no-proxy 会覆盖它们；工作区自己的代理设置优先。 |
ECHOLOT_CERT_PASSPHRASE | send、run、mqtt | 用 --cert 或 --key 给出的密钥或 PKCS#12 文件的口令。 |
ECHOLOT_MQTT_PASSWORD | mqtt | Broker 的密码。 |
ECHOLOT_MCP_TOKEN | mcp serve --http | 客户端发送的 Bearer 令牌；否则使用随机令牌。 |
ECHOLOT_WEBHOOK_TOKEN | flow serve | Webhook 调用方发送的令牌；否则使用随机令牌。 |
ECHOLOT_BROWSER | mcp sign-in | 用来打开登录页面的命令，代替默认浏览器。 |
ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY | agent | 模型提供商的 API 密钥。 |
NO_COLOR | run | 纯文本的控制台输出。 |
输出和退出码
结果输出到标准输出：响应正文、报告、订阅打印的行。进度、警告、测试结果和耗时输出到标准错误，所以你可以把输出通过管道传给其他命令：
echolot send https://demo.echolot.dev/v1/products/TNT-MH-2P | jq .name| 退出码 | 含义 |
|---|---|
0 | 一切正常，每项检查都通过。 |
1 | 出了问题：没有响应、检查或测试失败、发现了问题（validate、spec lint）、有破坏性更改（graphql diff）、gRPC 状态不是 OK、MQTT 连接被拒绝、智能体没有完成。 |
22 | 仅限 echolot send：响应状态为 400 或更高，与 curl --fail 相同。 |
64 | 命令行本身有误：未知选项、缺少文件、环境不存在。会打印原因。 |
下一步
- 运行工作区以及在 CI 中运行。
- 向智能体提供工作区。
- 在 CI 中测试 API，一篇教程。