# 安装和运行 CLI
Apifox CLI 是一个命令行工具，可用于在本地终端、CI/CD 平台或 AI Agent 中调用 Apifox 能力。
它不仅可以运行场景用例和测试套件，也可以管理接口文档、数据模型、Mock、环境变量、测试用例、分支、文档等项目资源。使用前需要先安装 Node.js 和 Apifox CLI。
## 安装 Apifox CLI
Apifox CLI 是基于 Node.js 开发的，所以得先装好 [Node.js](https://nodejs.org/en/download/package-manager/)，要求 Node.js 版本不能低于 `v16`。
在系统上全局安装 Apifox CLI，这样就能在任何地方运行它。
```bash
npm i -g apifox-cli@latest --registry=https://registry.npmmirror.com/
```
```bash
npm install -g apifox-cli
```
```text
阅读说明并帮我安装 Apifox CLI：https://apifox.com/apifox-cli-installation-guide.md
```
可以通过以下命令确认是否安装成功。
```bash
node -v && apifox -v && which node && which npm && which apifox
```
如果安装成功，运行上面的命令后会直接显示版本号和安装路径。
请在 Windows 的 cmd（命令提示符） 中运行以下命令，不要在 PowerShell 中执行：
```bash
node -v && apifox -v && where node && where npm && where apifox
```
如果安装成功，运行上面的命令后会直接显示版本号和安装路径。
如果你在执行 Apifox CLI 安装命令时，发现命令一直卡住、没有任何输出，也没有报错，通常是网络或权限相关问题。
建议直接将「完整命令 + 终端输出」交给 AI，让其协助判断具体原因。
## 更新 Apifox CLI
用下面的命令可以升级 Apifox CLI。
```bash
npm install apifox-cli@latest -g
```
## 登录账号
安装完成后，建议先登录 Apifox 账号。登录后，CLI 会把账号信息保存在本机，后续命令默认使用当前账号。
```bash
apifox auth login
```
如果你已经有访问令牌，也可以直接使用：
```bash
apifox auth login --with-token
```
查看已登录账号和当前使用的账号：
```bash
apifox auth status
```
如果本机登录了多个账号，可以切换当前账号：
```bash
apifox auth switch
```
## SKILL：配合 AI Agent 使用
如果你希望在 Cursor、Claude Code、Trae、Codex 等 AI Agent 中使用 Apifox CLI，可以安装配套 Skill：
```bash
apifox skill install
```
安装后，AI Agent 可以更好地理解 Apifox CLI 的命令、参数和工作流，用于查询项目资源、创建或更新接口文档、运行测试、管理分支等操作。
## 常用命令入口
查看 CLI 支持的完整命令：
```bash
apifox --help
```
查看某个命令的详细用法：
```bash
apifox --help
```
例如：
```bash
apifox endpoint --help
apifox run --help
```
## 运行测试场景
运行场景用例是 Apifox CLI 的常见用途之一。你需要先在 Apifox 中创建并编排好场景用例，之后就能像在图形界面一样，在命令行中运行场景用例并得到测试报告。
Apifox CLI 支持两种运行方式：
1. **运行在线数据**：适合实时场景
2. **导出数据运行**：适合离线场景
### 运行在线数据
在场景用例中，切换到 CI/CD 标签页。
配置运行环境、测试数据、循环次数、间隔停顿时间等。界面上更改不同的值，会影响下方生成的实际命令。
- 运行环境，影响 `-e `
- 测试数据，影响 `-d `
- 循环次数，影响 `-n `
- 间隔停顿，影响 `--delay-request `
- 环境/全局变量值，如果选择 “导出本地值使用”，则可以在界面发现导出入口将当前项目的环境/全局变量本地值导出到文件内，并且影响 `--variables `。需要将这个导出文件放到 CLI 运行机器内，并将此文件路径填入 `--variables ` 中。关于 “使用远程值” 和 “导出本地值使用” 的区别，[在此处了解更多](https://docs.apifox.com/5632037m0#不同运行方式间使用不同的环境全局变量值的规则)。
- 如果你的场景用例中同时使用了保存在本地的数据库连接配置，则产品界面会引导导出配置到本地文件，并且影响 `--database-connection `。需要将这个导出文件放到 CLI 运行机器内，并将此文件路径填入 `--database-connection ` 中。
:::tip[]
建议数据库连接配置，使用变量形式保存，这样可以协同使用并且**无需**在 CLI 运行时增加`--database-connection `选项。[了解更多](https://docs.apifox.com/database-connections.md)
:::
在 CI/CD 平台中，选择 “CLI 命令行”。
点击 “添加 Access Token” 按钮，然后 “生成 Token”。
:::highlight purple
了解更多关于[访问令牌](https://docs.apifox.com/api-access-token.md)的信息。
:::
点击命令复制。
把命令粘贴到命令行中运行，即可在命令行看到测试报告。
### 导出数据运行
在场景用例中，切换到 CI/CD 标签页。
配置运行环境、测试数据、循环次数、间隔停顿时间等。
在 CI/CD 平台中，选择 “CLI 命令行”，然后切换到 “导出数据运行”。
把场景用例导出成 JSON 文件。
复制下方显示的命令。
把命令粘贴到命令行中运行，即可看到命令行测试报告。
:::tip[]
第二步中，在界面内的设置如 “运行在线数据” 一样会自动影响下方 CLI 使用的选项及值。需要注意的是通过此种方式运行，环境/全局变量使用的是随场景用例一起导出的文件内的值。[在此处了解更多](https://docs.apifox.com/5632037m0#不同运行方式间使用不同的环境全局变量值的规则)。
:::
## CLI 测试报告
跑完 CLI 后，你会得到一份命令行测试报告，包含场景用例的执行统计数据，以及失败请求的验证和断言信息。
在运行 CLI 的文件夹里还能找到 `/apifox-reports/` 目录，里面有 HTML 格式的 CLI 测试报告。
## 命令选项
Apifox CLI 提供了丰富的配置选项来自定义测试集合的运行。详情可以看 [CLI 命令选项](https://docs.apifox.com/cli-command-options.md)。
## 在 CI/CD 中使用 Apifox CLI
Apifox CLI 支持和各种流水线工具集成，比如 Jenkins、GitLab、GitHub Actions 等。想了解更多可以看看 [CI/CD 集成](https://docs.apifox.com/cicd.md)。