你的 API 工作区通常存在于 GUI 图形界面中，而日常开发、测试和自动化执行往往发生在终端里。两者之间频繁切换上下文，不仅会浪费时间，还会打断专注度。更重要的是，在 CI/CD 流水线、自动化脚本或 AI Agent 会话中，GUI 往往根本无法使用。Apifox CLI 正是为了解决这一问题：它把完整的 Apifox 平台能力——包括接口测试、API 接口、数据模型、环境配置、Mock 期望以及文档管理——直接带到你已经打开的 Shell 终端中。
首先要说清楚：Apifox CLI 并不是另一个 curl。如果你只是想临时发送一个 GET 请求，并手动查看返回的 JSON 响应，那么 curl 和 HTTPie 已经足够高效，而终端和 TUI REST 客户端也能满足交互式调试需求。Apifox CLI 的定位，是你的 API 工作区专属命令行客户端：它可以执行你在 Apifox 中搭建好的测试场景，读取与更新 API 契约，并在项目内外完成接口规范的导入导出，而且这些操作都可以通过脚本、CI 或 AI Agent 直接调用。
这里的“常驻终端”具体指什么
大多数终端 HTTP 工具一次只能处理单个请求，而 Apifox CLI 面向的是整个 API 项目级别的操作。它的命令体系覆盖 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，用来提示你或 AI Agent 下一步应该执行什么。这个细节看似不起眼，却显著改善了命令行使用体验：由 CLI 主动引导工作流，而不是默认你已经记住全部命令和参数。
一键安装
Apifox CLI 以 npm 包（apifox-cli）的形式发布，支持 macOS、Linux 和 Windows，运行环境要求 Node.js 16 或更高版本。
npm install -g apifox-cliapifox --version
安装完成后，使用 API 访问令牌登录即可。你可以在 Apifox 应用中获取 Token：点击头像，进入“账户设置”，复制“API 访问令牌”下方的 Token。
apifox login --with-token
Token 会保存到 ~/.apifox/config.toml 中，因此不要将其提交到代码仓库，也不要出现在日志里；在 CI/CD 环境中，更推荐使用 Secret，并在每次执行时通过 --access-token 参数传入。四个全局标志（Flag）基本覆盖了主要上下文：--project 用于指定项目，--branch 用于切换分支，--access-token 用于覆盖本地已保存的登录态，--api-base-url 则用于将 CLI 指向私有化部署的 Apifox 实例。《Apifox CLI 身份验证指南》详细说明了如何在 CI 中安全使用 Token。
运行你通过可视化界面构建的测试
这正是 Apifox CLI 的核心工作流。你可以先在 Apifox 可视化编辑器中创建 API 测试场景，例如串联多个请求、从上一个响应中提取变量并注入到下一个请求中，同时配置状态码断言和响应体断言。随后，就能在任何支持 Shell 的环境中直接运行这些自动化测试。
# 从测试场景的 CI/CD 标签页中复制此命令（包含 ID）apifox run -t
当所有断言都成功通过时，命令退出码为 0；只要任意一步失败，退出码就会变成非零值，因此 CI 流水线可以直接据此控制构建成败，无需额外编写胶水代码。通过切换 -e 参数，同一个测试场景就能分别指向开发环境、预发布环境或生产环境。若再配合 CSV 或 JSON 数据文件，CLI 还可以按每一行数据循环执行测试场景，这就是常见的数据驱动 API 测试方式，无需重复配置测试步骤。如果你准备从零开始，分步式 REST API 教程能够带你从安装一路完成首次绿色通过。
测试报告支持四种输出格式：cli 会在终端中显示逐步执行结果，而 html、json 和 junit 会保存到 apifox-reports/ 目录，方便接入仪表盘、CI 产物和质量分析系统。你也可以同时组合使用，例如 -r cli,junit。测试报告指南展示了这些格式各自的输出效果和适用场景。
如果你不希望依赖个人电脑长期执行任务，还可以通过 runner 和 scheduled-task 命令管理自托管 runner 与定时任务，这也是 Apifox 定时 API 测试背后的同一套执行机制。
无需打开应用即可管理 API 契约
这是很多终端 API 测试工具不具备的能力。Apifox CLI 不仅可以运行测试，还能直接读取和修改 API 定义本身：
apifox endpoint list --project
接口定义、数据模型、目录结构、环境、变量、鉴权方案以及可复用组件库，都可以通过命令行查询和编辑。mock 命令用于管理 mock 期望，也就是 mock 服务返回的固定请求响应组合。doc 和 docs-site 命令可用于管理已发布的 API 文档和文档站点。对于 WebSocket 和 Socket.IO 接口，也分别提供了专属命令分组，而 database-connection 则用于管理测试场景依赖的数据库连接配置。
在导入导出方面，Apifox CLI 支持多种主流 API 规范格式：包括 OpenAPI 3.x、Swagger 2.0 以及 Postman 集合。这让它非常适合用于 API 迁移、接口同步和规范治理：你可以从其他系统拉取接口规范，导入到 Apifox，再通过脚本或版本控制管理整个转换流程。
apifox import openapi.json --project
专为 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%，Token 消耗降低了约 25%；更详细的数据拆解可参考相关分析文章。
第四，是明确的权限控制。默认情况下，AI 发起的分支写入会被拦截，必须先由人工开启“外部 AI 编辑权限”（在 Apifox 客户端 2.8.32 或更高版本中，路径为“项目设置” -> “功能设置” -> “AI 功能设置”）。另一种更稳妥的方式是使用 AI 分支：这是一个隔离环境，Agent 可以在其中导入资源、完成修改，再以合并请求（merge request）的形式提交回主流程，等待人工评审。那些未被继续修改的 AI 分支会在 24 小时后自动归档，避免试验性内容不断堆积。也就是说，即使第一版 API 契约是由 Agent 生成的，整体流程仍然保持可审查、可回溯。
Apifox CLI 不是什么
这里也有必要明确三个边界。基于真实能力选择 API 工具，远比后续才发现限制更高效。
它不是交互式请求客户端。没有哪个命令专门用于发送临时 POST 请求并格式化展示响应结果；这类工作仍然更适合交给 curl、HTTPie 或各类 TUI 客户端，而且它们在这方面做得更成熟。
它不是开源软件。该 npm 包属于专有软件，npm 是目前唯一的安装方式，除了执行 --help 之外，其他功能都需要 Apifox 账号。免费版已经覆盖本文介绍的主要工作流，但如果你的组织对可审计许可证有刚性要求，那么更适合考虑开源 runner 方案。
它也不是独立运行的本地工具。CLI 本质上是 Apifox 平台在终端中的延伸：测试场景、API 接口、环境配置等资源都保存在 Apifox 项目里，而不是本地文件中。正因为这种设计，你才能在 API 设计、接口测试、Mock 和文档管理之间共享同一份唯一事实源（source of truth）。
它在终端工具箱中的定位
与其他 API runner 相比，真正的差异在于测试内容是在哪里编写的。Newman 和 Postman CLI 运行的是在 Postman 中创建的 collection；Hurl 和 Bruno 运行的是基于文本文件定义的测试；而 Apifox CLI 运行的是在可视化编辑器中搭建的测试场景，并且这个编辑器同时承载你的 API 契约、Mock 配置和接口文档。关于 Apifox CLI 与 Newman 的对比，可以进一步参考更深入的专题文章；如果你关心整个终端 API 测试工具生态，也可以查看相关排名与汇总。
对于大多数研发团队来说，一个很实用的组合方式是：继续保留 curl 或 xh 处理临时请求的使用习惯，同时让 apifox run 在 CI/CD 中负责执行正式测试套件。GitHub Actions 教程中还提供了可直接复制粘贴的流水线示例，方便快速接入。
FAQ
Apifox CLI 是免费使用的吗？ 是的。该包可以通过 npm 免费安装，Apifox 免费版的额度也足以支持创建测试场景并通过 CLI 执行。付费版本主要增加的是团队协作规模与高级能力，而不是基础 CLI 使用权限。
它会替代 curl 或 HTTPie 吗？ 不会，而且它本身也不是为此设计的。curl、HTTPie 适合发送临时请求做快速调试；Apifox CLI 则适合运行已保存的 API 测试场景，以及管理项目中的接口资源。对大多数开发者来说，这两类工具通常会长期共存。
它可以在 CI 中完全无头（headless）运行吗？ 可以。你只需要通过 CI Secret 传入 --access-token，再使用测试场景 ID 执行 apifox run，最后根据退出码控制构建流程即可。在 runner 上不需要安装桌面客户端。
它支持导入和导出哪些格式？ 支持双向导入与导出 OpenAPI 3.x、Swagger 2.0 和 Postman collection，能够覆盖常见的 API 迁入、迁出和同步需求。
AI agent 如何安全地使用它？ 关键在于“数据模型-校验-写入”流程与权限网关：cli-schema validate 可以在格式错误的 payload 写入前完成拦截，而 AI 分支可以把 agent 的修改隔离起来，直到人工确认合并。若想了解它在 Agent 场景下的真实使用方式，可以参考如何在 Claude Code 中使用 Apifox CLI。
终端，本来就是你运行自动化测试、执行脚本以及让 AI Agent 真正开始工作的地方。把 API 客户端能力也直接放进这个环境中，最后那一步来回切换工具和上下文的成本，基本就可以省掉了。你可以先下载 Apifox，再通过 npm 安装 CLI，亲手把一个测试场景完整跑通；等你不再只满足于 run 这一条命令，而是希望进一步管理 API 项目资源时，再去访问 Apifox CLI 页面查看完整命令参考即可。
开发必备：API 全流程管理神器 Apifox
介绍完以上内容，也想额外推荐一个对开发者非常重要的效率工具——Apifox。作为一款集 API 文档、接口调试、API 设计、自动化测试、Mock、测试管理于一体的平台，Apifox 已成为很多团队提升研发效率、统一 API 协作流程的首选工具。
如果你正在开发项目，不妨体验一下它直观且友好的界面设计。Apifox 完全兼容 Postman 和 Swagger 数据格式，接口导入非常方便，即使是新手开发者也能快速上手，点击这里即可注册使用。
值得一提的是，除了个人开发者和常规团队协作场景外，对于有高安全合规要求、或需要在内网环境协同开发的企业，Apifox 还提供深度定制的私有化部署方案。
