你的 API 工作区存在于 GUI 中，而你的日常工作则是在终端里进行的。两者之间的每一次上下文切换都会消耗时间并分散注意力。而且在 CI 流水线或 AI agent 会话中，GUI 甚至根本不是一个可选项。Apifox CLI 弥合了这一差距：它将整个 Apifox 平台——包括测试、接口、数据模型、环境、mock 期望以及文档——直接带到了你已经打开的 Shell 提示符中。

首先需要明确的一点是：Apifox CLI 并不是另一个 curl。如果你只是想发送一次性的 GET 请求并肉眼查看 JSON 响应，curl 和 HTTPie 已经做得足够好，而终端和 TUI REST 客户端的汇总则涵盖了交互式操作的需求。Apifox CLI 是你 API 工作区专属的客户端：它可以运行你构建的测试场景，读取并更新 API 契约，以及在项目内外导入导出接口规范，而所有这些操作都可以通过脚本或 Agent 调用的命令来完成。

这里的“常驻终端”具体指什么

终端 HTTP 工具一次通常只能处理一个请求。而 Apifox CLI 则是在项目级别进行操作。它的命令集涵盖了 40 多个分组，主要归纳为以下五大类任务：

每个命令都支持 --help，输出结果采用结构化的 JSON 格式，并且大多数响应中都包含 agentHints.nextSteps，用于提示你（或你的 Agent）下一步该运行什么。最后一个细节看似微不足道，但它却改变了工具的使用体验：由 CLI 来引导工作流，而不是默认你已经记住了所有命令。

一键安装

该 CLI 以 npm 包（apifox-cli）的形式发布，支持在 macOS、Linux 和 Windows 上运行。它需要 Node.js 16 或更高版本。

npm install -g apifox-cliapifox --version

然后使用 API 访问令牌登录。你可以从 Apifox 应用中获取它：点击你的头像，打开“账户设置”，然后复制“API 访问令牌”下方的 Token。

apifox login --with-token <YOUR_TOKEN>

Token 会保存在 ~/.apifox/config.toml 中，因此请避免将其提交到代码仓库或暴露在日志中；在 CI 中，建议改用 Secret，并在每次运行时通过 --access-token 参数来传入。四个全局标志（Flag）覆盖了大部分上下文：--project 用于选择项目，--branch 用于选择分支，--access-token 用于覆盖已保存的登录信息，而 --api-base-url 则将 CLI 指向私有化部署的 Apifox 实例。《Apifox CLI 身份验证指南》详细介绍了如何在 CI 中使用 Token。

运行你通过可视化界面构建的测试

这就是该 CLI 围绕构建的工作流。您可以在 Apifox 的可视化编辑器中编写测试场景：链式请求、从一个响应中提取并注入到下一个响应中的变量，以及对状态和 body 的断言。然后，您可以在任何支持 shell 的地方运行它。

# 从测试场景的 CI/CD 标签页中复制此命令（包含 ID）apifox run -t <scenario_id> -e <env_id> -r cli

当所有断言都通过时，该命令退出码为 0；当有任何失败时，退出码为非零值，因此流水线可以直接利用它进行卡点，无需额外的胶水代码。通过更换 -e 参数，可以让同一个测试场景指向开发、预发布或生产环境。给它喂一个 CSV 或 JSON 文件，它就会针对每一行数据循环执行该测试场景，这就是在不重复步骤的情况下实现数据驱动测试的方法。如果您是从零开始，分步式 REST API 教程将带您完成从安装到首次成功运行（绿色通过）的全过程。

报告输出支持四种格式：cli 在终端打印分步结果，而 html、json 和 junit 则会保存在 apifox-reports/ 目录中，用于仪表盘和 CI 产物。您可以自由组合它们，例如 -r cli,junit。测试报告指南展示了每种格式的具体样式。

对于不希望依赖个人电脑运行的场景，可以使用 runner 和 scheduled-task 命令来管理自托管的 runner 和定时任务执行，这也是 Apifox 定时 API 测试背后的相同运行机制。

无需打开应用即可管理 API 契约

这是其他终端测试工具所不具备的功能。运行测试的同一个 CLI 还可以读写 API 定义本身：

apifox endpoint list --project <project_id>apifox schema get <schema_id>apifox environment listapifox mock list

接口、数据模型、目录、环境、变量、鉴权组件和可复用的组件库都是可查询和编辑的。mock 命令用于管理 mock 期望，即 mock 服务端返回的固定请求与响应对。doc 和 docs-site 命令可用于操作已发布的文档和文档站。WebSocket 和 Socket.IO 接口有它们专属的分组，而 database-connection 则涵盖了测试场景所读取的数据库连接配置。

导入和导出支持各种主流格式：OpenAPI 3.x 和 Swagger 2.0（大多数工具链标准化的规范），以及 Postman 集合。这使得 CLI 成为迁移脚本中的桥梁：从一个系统拉取规范，将其推送到 Apifox，并对整个流转过程进行版本控制。

apifox import openapi.json --project <project_id>apifox export --format openapi

专为 AI Agent 驱动而设计

CLI 2026 年的版本紧紧围绕着一个核心理念：AI 编码 Agent 应该能够像人类一样安全地操作您的 API 工作空间。四个关键部分共同实现了这一点。

首先是结构化输出。每个命令都会返回 Agent 可以解析的 JSON，并且 agentHints.nextSteps 会告知它在获得每个结果后下一步该做什么，包括如何从错误中恢复。

其次，是公开的输入数据模型。apifox cli-schema list 和 apifox cli-schema get 会公开每个写入命令所期望的确切 JSON 结构，而 apifox cli-schema validate 则会在任何内容进入项目之前校验 payload。安全的写入流程总是相同的：获取数据模型，生成 JSON，校验它，然后才运行 create 或 update。

第三，是一个打包的技能。skill 命令以 Agent 可以直接加载的形式交付 CLI 的运行知识，这就是我们构建 Apifox CLI skill 背后的故事。根据我们自己的测量，与猜测 payload 的 Agent 相比，通过 CLI 数据模型工作的 Agent 减少了大约 30% 的工具调用和 25% 的 Token 消耗；具体数据在这篇分析中进行了拆解。

第四，权限限制。默认情况下，来自 AI 的分支写入会被阻止，直到人工启用“外部 AI 编辑权限”（在 Apifox 客户端 2.8.32 或更高版本中，路径为“项目设置” -> “功能设置” -> “AI 功能设置”）。另一种选择是 AI 分支：这是一个隔离的分支，Agent 在其中导入它需要的资源，进行编辑，并将结果作为合并请求（merge request）返回以供评审。未被修改的 AI 分支会在 24 小时后自动归档，因此实验不会堆积。即使是由 Agent 编写初稿，您的 API 契约也依然保持可评审状态。

Apifox CLI 不是什么

这里明确指出三个局限性，因为基于真实信息选择工具，总好过以后才发现局限。

它不是一个交互式的请求客户端。没有哪个命令可以让你发送临时 POST 请求并美化输出响应；curl、HTTPie 和 TUI 客户端更适合做这件事，而且它们做得更好。

它不是开源的。该包是专有软件，npm 是唯一的安装通道，执行 --help 以外的任何操作都需要 Apifox 账号。免费版涵盖了这里介绍的完整工作流，但如果可审计的许可证是刚性需求，我们诚恳地推荐使用开源的 runner。

它不是独立运行的。CLI 是该平台的终端延伸：测试场景、接口和环境都存在于你的 Apifox 项目中，而不是本地文件中。正是这种折衷，让你在设计、测试、mock 和文档中拥有单一的唯一事实源（source of truth）。

它在终端工具箱中的定位

与其他 runner 相比，区别在于编写发生在哪里。Newman 和 Postman CLI 运行在 Postman 中编写的集合（collections）；Hurl 和 Bruno 运行以文本文件编写的测试；而 Apifox CLI 运行在可视化编辑器中编写的测试场景，该编辑器同时保存了你的契约、mock 和文档。Apifox CLI 与 Newman 的对比更加深入，在最优秀的基于终端的 API 测试工具汇总中对整个领域进行了排名。

对大多数团队来说，一个行之有效的配置是：保持对 curl 或 xh 的肌肉记忆来进行临时测试，并让 apifox run 在 CI 中运行测试套件。GitHub Actions 教程中提供了一个可供复制粘贴的流水线，供你快速上手。

FAQ

Apifox CLI 是免费使用的吗？ 是的。该包可以从 npm 免费安装，且 Apifox 的免费版额度涵盖了构建测试场景以及通过 CLI 运行它们。付费方案增加的是团队规模的功能，而非基础的 CLI 访问权限。

它会替代 curl 或 HTTPie 吗？ 不会，它也无意于此。这些工具用于发送临时请求；而 Apifox CLI 则用于运行已保存的测试场景并管理项目资源。大多数终端最终会同时保留这两者。

它可以在 CI 中完全无头（headless）运行吗？ 可以。通过 CI 密钥中的 --access-token 进行鉴权，使用你的测试场景 ID 运行 apifox run，并根据退出码控制构建流程。在 runner 上不需要安装桌面版。

它支持导入和导出哪些格式？ 支持双向导入和导出 OpenAPI 3.x、Swagger 2.0 和 Postman collection。这涵盖了迁入和迁出的需求。

AI agent 如何安全地使用它？ 通过“数据模型-校验-写入”流程和权限网关：cli-schema validate 可以在格式错误的 payload 写入前将其拦截，而 AI 分支则可以将 agent 的修改隔离，直到人工进行合并。若想查看它在 agent 内部的实际运行方式，请参阅如何在 Claude Code 中使用 Apifox CLI。

终端是你的测试已经运行、agent 已经工作的地方。将 API 客户端也放在这里，可以省去最后的上下文切换步骤。下载 Apifox，从 npm 安装 CLI，并端到端运行一个测试场景；当你准备好使用 run 以外的其他命令时，可以访问 Apifox CLI 页面 获取完整的命令参考手册。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。