Apifox CLI：运行在终端里的 API 客户端

你的 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 调用的命令轻松完成。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

这里的“运行在终端里”意味着什么

终端 HTTP 工具一次只能处理一个请求。而 Apifox CLI 则在项目层面上运行。它的命令集包含 40 多个分组，可归纳为五项核心任务：

任务	命令
运行测试	`run`, `test-scenario`, `test-suite`, `test-case`, `test-data`, `test-report`
管理契约	`endpoint`, `schema`, `folder`, `common-parameter`, `response-component`, `security-scheme`
发布文档与 mock	`doc`, `docs-site`, `shared-doc`, `mock`
配置与连接	`environment`, `variables`, `vault`, `database-connection`, `websocket`, `socketio`
团队协作	`branch`, `merge-request`, `runner`, `scheduled-task`, `audit-log`, `import`, `export`

每个命令都支持 --help，输出均为结构化的 JSON，并且大多数响应中都包含 agentHints.nextSteps，用于提示你（或你的 Agent）下一步该运行什么。最后这个细节看似微不足道，却改变了工具的使用体验：CLI 能够引导整个工作流，而不是假设你已经把所有命令熟记于心。

一键安装

该 CLI 作为 npm 包发布（apifox-cli），支持 macOS、Linux 和 Windows 平台。运行环境需要 Node.js 16 或更高版本。

npm install -g apifox-cli
apifox --version

接着，使用 API 访问令牌登录。获取方式：在 Apifox 应用中点击头像，打开“账号设置”（Account Settings），复制“API 访问令牌”（API Access Token）下的 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 的可视化编辑器中编写测试场景：包括请求链式调用、从一个响应中提取变量并注入到下一个请求中，以及对 status 和 body 进行断言。然后，你可以在任何支持 shell 的环境中运行它。

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

当所有断言都通过时，命令返回退出码 0；当出现任何失败时，则返回非零值，因此流水线无需额外的胶水代码即可直接将其用作质量门禁。只需修改 -e 参数，即可将同一个测试场景指向开发（dev）、预发布（staging）或生产（production）环境。为其提供 CSV 或 JSON 文件，它就会对每一行数据迭代运行该测试场景，无需重复步骤即可实现数据驱动测试。如果你是从零开始，分步式 REST API 教程将带你完成从安装到首次运行成功的全过程。

测试报告支持四种格式输出：cli 会在终端中逐步打印结果，而 html、json 和 junit 则会存放在 apifox-reports/ 目录中，供仪表盘和 CI 构建产物使用。你可以自由组合这些格式，例如 -r cli,junit。测试报告指南展示了每种格式的具体效果。

对于不希望依赖本地电脑的运行任务，runner 和 scheduled-task 命令可以管理自托管 runner 和定时执行任务，这也是 Apifox 定时 API 测试功能背后的底层机制。

无需打开 App 即可管理 API 契约

这是其他终端测试工具所不具备的功能。用于运行测试的同一个 CLI，可以直接读取和写入 API 接口定义/规范本身：

apifox endpoint list --project <project_id>
apifox schema get <schema_id>
apifox environment list
apifox 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。skill 命令以 Agent 可以直接加载的形式提供 CLI 的操作知识，这也是我们构建 Apifox CLI Skill 背后的故事。在我们自己的测算中，相比盲目猜测 Payload 的 Agent，通过 CLI 数据模型工作的 Agent 调用的工具次数减少了约 30%，消耗的 Token 减少了约 25%；详细数据可以参阅这篇分析。

第四是权限把控。默认情况下，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 和文档之间拥有统一的单一事实来源（Single Source of Truth）。

它在终端工具箱中的定位

与其他 runner 相比，区别在于内容的编辑编写发生在哪里。Newman 和 Postman CLI 运行的是在 Postman 中编写的 Collection；Hurl 和 Bruno 运行的是以文本文件形式编写的测试；而 Apifox CLI 运行的则是在可视化编辑器中编写的测试场景，该编辑器同时托管了你的 API 契约、mock 和文档。Apifox CLI 与 Newman 的对比文章对此进行了更深入的探讨，完整工具阵容已在终端 API 测试工具汇总中进行了排名。

适合大多数团队的高效配置：肌肉记忆保留 curl 或 xh 用于日常随手调试，让 apifox run 在 CI 中运行测试套件。GitHub Actions 指南中提供了可直接复制粘贴的 Pipeline 代码供入门使用。

FAQ

Apifox CLI 是免费使用的吗？ 是的。该包可以从 npm 免费安装，Apifox 的免费版涵盖了构建测试场景并通过 CLI 运行它们的功能。付费计划增加的是团队规模的功能，而不是限制基础 CLI 的使用。

它会替代 curl 或 HTTPie 吗？ 不会，它也没有试图这么做。那些工具用于发送即时请求；而 Apifox CLI 则是运行保存的测试场景并管理项目资源。大多数终端最终都会同时保留这两类工具。

它能在 CI 中完全以 Headless（无头）模式运行吗？ 是的。使用 CI secret 中的 --access-token 进行鉴权，通过场景 ID 运行 apifox run，并根据退出代码控制构建流程。Runner 上不需要安装桌面版。

它支持导入和导出哪些格式？ 支持 OpenAPI 3.x、Swagger 2.0 和 Postman Collection 的双向导入和导出。这涵盖了数据迁入与外部集成的需求。

AI Agent 如何安全地使用它？ 通过“数据模型校验-写入”流程和权限关口：cli-schema validate 可以在格式错误的 payload 写入前进行拦截，而 AI 分支可以在人工合并之前将 Agent 的修改进行隔离。可以在《如何在 Claude Code 中使用 Apifox CLI》中查看它在 Agent 内部的具体运行方式。

终端是你运行测试和 Agent 开展工作的地方。把 API 客户端也放在终端里可以消除最后的上下文切换。下载 Apifox，从 npm 安装 CLI，并端到端地运行一个测试场景；当你准备好了解 run 之外的命令时，Apifox CLI 页面提供了完整的命令参考。