Apifox CLI 用于在终端或 CI/CD 流程中操作 Apifox 项目。功能上，覆盖了自动化测试运行、接口设计资源维护、环境与变量管理、项目数据导入导出、在线文档发布、分支协作和项目管理等。适用于通过脚本或流水线批量执行 Apifox 操作，在 AI Agent 中与代码库协同、高效管理 Apifox 项目资源。基础语法#
身份验证#
在访问你的私有项目前，需要先登录或设置 访问令牌。| 命令 | 说明 | 示例 |
|---|
login | 使用令牌登录，令牌会持久化到本地。 | apifox login --with-token <您的令牌> |
logout | 退出登录。 | apifox logout |
whoami | 显示当前登录的用户信息。 | apifox whoami |
CLI Schema#
CLI Schema 是一项通用子命令，在创建或更新复杂资源时，往往需要构建复杂的请求结构，为了降低执行失败率 —— 推荐先使用 cli-schema 查看对应资源执行命令的 JSON Schema（cli-schema get 命令），再用同一个资源的 schema key 校验（cli-schema validate 命令）本地 JSON 文件。schema key 通常由命令路径和动作组成，例如 endpoint-create、test-scenario-update、merge-request-create。| 命令 | 说明 | 示例 |
|---|
cli-schema list | 列出当前 CLI 支持查看和校验的数据结构。 | apifox cli-schema list |
cli-schema get | 查看某个命令的 --file JSON 文件结构。 | apifox cli-schema get endpoint-create |
cli-schema validate | 校验 JSON 文件是否符合指定结构。 | apifox cli-schema validate endpoint-create --file ./endpoint.json |
团队与项目#
团队和项目是使用 CLI 操作 Apifox 数据的起点。创建项目时先找到团队 ID，后续查看接口、环境、场景用例等项目内资源时，都需要用到项目 ID。如果长期在同一个项目中工作，可以把常用默认 projectId 记录到当前工作区的 .apifox/settings.json，供 AI Agent 读取：当用户需求没有明确指定项目时，AI Agent 应优先使用这里保存的 projectId。项目内资源命令通常使用 --project <projectId> 指定项目，可使用 --branch <branchName> 指定分支；不传 --branch 时默认主分支。资源命令不需要传 --type，--type 主要用于 branch、folder 等需要选择类型的命令。团队管理#
查看当前账号可访问的团队。创建项目时通常 需要先通过团队命令确认 teamId。| 命令 | 说明 | 示例 |
|---|
team list | 列出当前账号可访问的团队。 | apifox team list |
team get | 查看指定团队的详情。 | apifox team get <teamId> |
项目管理#
| 命令 | 说明 | 示例 |
|---|
project list | 列出所有项目（ID、名称、描述）。 | apifox project list |
project get | 查看特定项目 的详细配置。 | apifox project get <projectId> |
project create | 在指定团队下创建普通项目。创建后可继续在客户端完善项目设置。 | apifox project create --team <teamId> --name "新项目" |
项目设置#
查看或更新项目级配置，适用于排查项目功能开关、权限配置、AI 写入权限等问题。| 命令 | 说明 | 示例 |
|---|
project settings get | 查看项目设置。 | apifox project settings get --project <projectId> |
project settings update | 通过数据文件更新项目设置。修改前建议先查看当前配置。 | apifox project settings update --project <projectId> --file <path> |
cli-schema get project-settings-update | 查看项目设置更新所需的 JSON Schema。 | apifox cli-schema get project-settings-update |
cli-schema validate project-settings-update | 校验项目设置更新数据文件。 | apifox cli-schema validate project-settings-update --file ./project-settings.json |
环境与变量#
适用于维护测试运行和接口调试所需的环境配置与变量值。运行场景用例、测试套件或调试接口前，可通过相关命令确认环境 ID、全局变量和团队变量。环境管理#
查看项目关联的环境配置信息，如前置 URL (Base URL) 和服务设置。| 命令 | 说明 | 示例 |
|---|
environment list | 列出项目下的所有环境。 | apifox environment list --project <projectId> |
environment get | 查看特定环境的配置详情（前置 URL 等）。 | apifox environment get <envId> --project <projectId> |
environment create | 创建新环境，适用于初始化项目或准备测试运行环境。 | apifox environment create <name> --project <projectId> --base-url <url> |
environment update | 更新环境配置。 | apifox environment update <envId> --project <projectId> --file <path> |
environment delete | 删除不再使用的环境。删除前应确认测试任务不再依赖它。 | apifox environment delete <envId> --project <projectId> |
cli-schema get environment-update | 查看环境更新所需的 JSON Schema。 | apifox cli-schema get environment-update |
cli-schema validate environment-update | 校验环境更新数据文件。 | apifox cli-schema validate environment-update --file ./environment.json |
变量管理#
管理项目运行时会读取的全局变量或团队变量。运行测试、调试接口或迁移环境配置前，可通过变量命令确认变量来源和值。| 命令 | 说明 | 示例 |
|---|
variables list | 按作用域列出变量。 | apifox variables list --project <projectId> --scope global |
variables get | 查看指定变量值。 | apifox variables get --project <projectId> --scope global --key <key> |
variables set | 新增或更新变量值。 | apifox variables set --project <projectId> --scope global --key <key> --value <value> |
variables delete | 删除变量。 | apifox variables delete --project <projectId> --scope global --key <key> |
variables import | 从本地文件导入变量。 | apifox variables import --project <projectId> --scope global --file <path> |
variables export | 导出变量到本地文件。 | apifox variables export --project <projectId> --scope global --output <path> |
接口设计资源管理#
适用于维护项目中的接口设计资源，包括 HTTP API 接口、数据模型、目录、Mock、公共参数、响应组件和鉴权组件。创建或更新复杂资源时，建议先通过 cli-schema get <schemaKey> 查看数据结构，再使用 cli-schema validate <schemaKey> --file <path> 校验数据文件，确认通过后再执行写入。HTTP API 接口#
endpoint 用于维护项目中的 HTTP API 接口 ，包括接口方法、路径、请求参数、请求体、响应定义、状态、标签和目录等内容。适用于查找接口 ID、批量调整接口状态，或在分支中修改接口定义。| 命令 | 说明 | 示例 |
|---|
endpoint list | 列出项目中的 HTTP API 接口，可用于查找接口 ID。 | apifox endpoint list --project <projectId> |
endpoint get | 查看接口详情，包括方法、路径、参数、请求体和响应定义。 | apifox endpoint get <endpointId> --project <projectId> |
endpoint create | 从 JSON 文件创建接口。适用于创建包含请求参数、请求体和响应定义的完整接口。 | apifox endpoint create --project <projectId> --file ./endpoint.json |
endpoint update | 更新接口。简单字段可用参数，复杂字段建议使用 --file。 | apifox endpoint update <endpointId> --project <projectId> --file ./endpoint.json |
endpoint delete | 删除接口。删除前应确认场景用例、接口用例或合并范围是否仍依赖它。 | apifox endpoint delete <endpointId> --project <projectId> |
cli-schema get endpoint-create | 查看接口创建所需的 JSON Schema。 | apifox cli-schema get endpoint-create |
cli-schema validate endpoint-create | 校验接口创建数据文件是否符合 Schema。 | apifox cli-schema validate endpoint-create --file ./endpoint.json |
cli-schema get endpoint-update | 查看接口更新所需的 JSON Schema。 | apifox cli-schema get endpoint-update |
cli-schema validate endpoint-update | 校验接口更新数据文件是否符合 Schema。 | apifox cli-schema validate endpoint-update --file ./endpoint.json |
数据模型#
schema 用于维护项目中的数据模型。数据模型可被接口参数、请求体、响应体等结构引用，适用于沉淀可复用的对象结构、枚举定义和通用数据格式。| 命令 | 说明 | 示例 |
|---|
schema list | 列出项目中的数据模型，可用于查找模型 ID。 | apifox schema list --project <projectId> |
schema get | 查看数据模型详情。 | apifox schema get <schemaId> --project <projectId> |
schema create | 从 JSON 文件创建数据模型。 | apifox schema create --project <projectId> --file ./schema.json |
schema update | 更新数据模型。修改被接口引用的模型前，应确认影响范围。 | apifox schema update <schemaId> --project <projectId> --file ./schema.json |
schema delete | 删除数据模型。删除前应确认接口或响应中不再引用它。 | apifox schema delete <schemaId> --project <projectId> |
cli-schema get schema-create | 查看数据模型创建所需的 JSON Schema。 | apifox cli-schema get schema-create |
cli-schema validate schema-create | 校验数据模型创建数据文件是否符合 Schema。 | apifox cli-schema validate schema-create --file ./schema.json |
cli-schema get schema-update | 查看 数据模型更新所需的 JSON Schema。 | apifox cli-schema get schema-update |
cli-schema validate schema-update | 校验数据模型更新数据文件是否符合 Schema。 | apifox cli-schema validate schema-update --file ./schema.json |
Markdown 文档#
doc 用于维护 API 管理树中的 Markdown 文档，适用于补充接口说明、接入说明、业务规则或其他接口设计相关内容。| 命令 | 说明 | 示例 |
|---|
doc list | 列出 Markdown 文档，用于查找文档 ID。 | apifox doc list --project <projectId> |
doc get | 查看 Markdown 文档详情，包括标题和内容等信息。 | apifox doc get <docId> --project <projectId> |
doc create | 创建 Markdown 文档。 | apifox doc create --project <projectId> --file ./doc.json |
doc update | 更新 Markdown 文档内容或配置。 | apifox doc update <docId> --project <projectId> --file ./doc-update.json |
doc delete | 删除 Markdown 文档。 | apifox doc delete <docId> --project <projectId> |
cli-schema get doc-create | 查看 Markdown 文档创建所需的 JSON Schema。 | apifox cli-schema get doc-create |
cli-schema validate doc-create | 校验 Markdown 文档创建数据文件是否符合 Schema。 | apifox cli-schema validate doc-create --file ./doc.json |
cli-schema get doc-update | 查看 Markdown 文档更新所需的 JSON Schema。 | apifox cli-schema get doc-update |
cli-schema validate doc-update | 校验 Markdown 文档更新数据文件是否符合 Schema。 | apifox cli-schema validate doc-update --file ./doc-update.json |
资源目录/文件夹#
folder 用于维护各类资源的目录树，例如接口目录、数据模型目录、场景用例目录、响应组件目录、测试数据目录等。操作目录时需通过 --type 指定资源类型；不同类型资源有独立的目录树。| 命令 | 说明 | 示例 |
|---|
folder list | 按资源类型列出目录，常用于查找父目录 ID。 | apifox folder list --project <projectId> --type endpoint |
folder create | 按资源类型创建目录。不同资源有独立目录树。 | apifox folder create --project <projectId> --type endpoint --name "新目录" |
folder move | 将目录移动到新的父级目录下。 | apifox folder move <folderId> --project <projectId> --type endpoint --parent <parentId> |
folder update | 更新目录名称、说明或父级。命令行参数会覆盖数据文件中的同名字段。 | apifox folder update <folderId> --project <projectId> --type endpoint --name "新目录名" |
folder delete | 删除目录。删除前应确认目录下资源是否仍需保留。 | apifox folder delete <folderId> --project <projectId> --type endpoint |
cli-schema get folder-create | 查看目录创建所需的 JSON Schema。 | apifox cli-schema get folder-create |
cli-schema validate folder-create | 校验目录创建数据文件是否符合 Schema。 | apifox cli-schema validate folder-create --file ./folder.json |
cli-schema get folder-update | 查看目录更新所需的 JSON Schema。 | apifox cli-schema get folder-update |
cli-schema validate folder-update | 校验目录更新数据文件是否符合 Schema。 | apifox cli-schema validate folder-update --file ./folder.json |
| type | 对应目录 |
|---|
endpoint | HTTP API 接口目录 |
schema | 数据模型目录 |
test-scenario | 场景用例目录 |
response-component | 响应组件目录 |
security-scheme | 鉴权组件目录 |
test-suite | 测试套件目录 |
test-data | 测试数据目录 |
--type 用于选择资源目录类型，不是目录名称。description 字段仅支持 endpoint 和 test-scenario 目录；其他目录类型只支持更新名称或父目录。
Mock 期望#
mock 用于维护接口下的 Mock 期望，适用于配置接口模拟返回、查看已有 Mock 规则或调整 Mock 数据。| 命令 | 说明 | 示例 |
|---|
mock list | 列出项目或指定接口下的 Mock 期望。 | apifox mock list --project <projectId> --http-api-id <endpointId> |
mock get | 查看某个 Mock 期望详情。需传入 Mock 期望 ID。 | apifox mock get <mockId> --project <projectId> |
mock create | 从 JSON 文件创建 Mock 期望。 | apifox mock create --project <projectId> --file ./mock.json |
mock update | 更新 Mock 期望。 | apifox mock update <mockId> --project <projectId> --file ./mock.json |
mock delete | 删除 Mock 期望。 | apifox mock delete <mockId> --project <projectId> |
cli-schema get mock-create | 查看 Mock 期望创建所需的 JSON Schema。 | apifox cli-schema get mock-create |
cli-schema validate mock-create | 校验 Mock 期望创建数据文件是否符合 Schema。 | apifox cli-schema validate mock-create --file ./mock.json |
cli-schema get mock-update | 查看 Mock 期望更新所需的 JSON Schema。 | apifox cli-schema get mock-update |
cli-schema validate mock-update | 校验 Mock 期望更新数据文件是否符合 Schema。 | apifox cli-schema validate mock-update --file ./mock.json |
公共参数#
common-parameter 用于维护可复用的公共参数，例如 Header、Query、Cookie 等。适用于统一管理多个接口共享的参数。| 命令 | 说明 | 示例 |
|---|
common-parameter list | 列出公共参数。 | apifox common-parameter list --project <projectId> |
common-parameter get | 查看公共参数详情。 | apifox common-parameter get <commonParameterId> --project <projectId> |
common-parameter create | 从数据文件创建公共参数。 | apifox common-parameter create --project <projectId> --file ./common-parameter.json |
common-parameter update | 更新公共参数。 | apifox common-parameter update <commonParameterId> --project <projectId> --file ./common-parameter.json |
common-parameter import | 从文件导入公共参数。 | apifox common-parameter import --project <projectId> --file ./common-parameters.json |
common-parameter export | 导出公共参数到本地文件。 | apifox common-parameter export --project <projectId> --output ./common-parameters.json |
cli-schema get common-parameter-create | 查看公共参数创建所需的 JSON Schema。 | apifox cli-schema get common-parameter-create |
cli-schema validate common-parameter-create | 校验公共参数创建数据文件。 | apifox cli-schema validate common-parameter-create --file ./common-parameter.json |
cli-schema get common-parameter-update | 查看公共参数更新所需的 JSON Schema。 | apifox cli-schema get common-parameter-update |
cli-schema validate common-parameter-update | 校验公共参数更新数据文件。 | apifox cli-schema validate common-parameter-update --file ./common-parameter.json |
响应组件#
response-component 用于维护可复用的响应组件。多个接口返回结构相同或相近时，可先创建响应组件，再在接口响应定义中引用。| 命令 | 说明 | 示例 |
|---|
response-component list | 列出响应组件。 | apifox response-component list --project <projectId> |
response-component get | 查看响应组件详情。 | apifox response-component get <responseComponentId> --project <projectId> |
response-component create | 从 JSON 文件创建响应组件。 | apifox response-component create --project <projectId> --file ./response-component.json |
response-component update | 更新响应组件。 | apifox response-component update <responseComponentId> --project <projectId> --file ./response-component.json |
response-component delete | 删除响应组件。删除前应确认接口响应定义是否仍引用它。 | apifox response-component delete <responseComponentId> --project <projectId> |
cli-schema get response-component-create | 查看响应组件创建所需的 JSON Schema。 | apifox cli-schema get response-component-create |
cli-schema validate response-component-create | 校验响应组件创建数据文件是否符合 Schema。 | apifox cli-schema validate response-component-create --file ./response-component.json |
cli-schema get response-component-update | 查看响应组件更新所需的 JSON Schema。 | apifox cli-schema get response-component-update |
cli-schema validate response-component-update | 校验响应组件更新数据文件是否符合 Schema。 | apifox cli-schema validate response-component-update --file ./response-component.json |
鉴权组件#
security-scheme 用于维护 Apifox 中的鉴权组件，对应 OpenAPI 的 securitySchemes。OAuth2、JWT、API Key、Bearer Token 等认证方式均可配置为鉴权组件，供接口引用。| 命令 | 说明 | 示例 |
|---|
security-scheme list | 列出项目中的鉴权组件。 | apifox security-scheme list --project <projectId> |
security-scheme get | 查看鉴权组件详情。 | apifox security-scheme get <schemeId> --project <projectId> |
security-scheme create | 从 JSON 文件创建鉴权组件。 | apifox security-scheme create --project <projectId> --file ./scheme.json |
security-scheme update | 更新鉴权组件。 | apifox security-scheme update <schemeId> --project <projectId> --file ./scheme.json |
security-scheme delete | 删除鉴权组件。删除前应确认接口是否仍引用它。 | apifox security-scheme delete <schemeId> --project <projectId> |
cli-schema get security-scheme-create | 查看 鉴权组件创建所需的 JSON Schema。 | apifox cli-schema get security-scheme-create |
cli-schema validate security-scheme-create | 校验鉴权组件创建数据文件是否符合 Schema。 | apifox cli-schema validate security-scheme-create --file ./scheme.json |
cli-schema get security-scheme-update | 查看鉴权组件更新所需的 JSON Schema。 | apifox cli-schema get security-scheme-update |
cli-schema validate security-scheme-update | 校验鉴权组件更新数据文件是否符合 Schema。 | apifox cli-schema validate security-scheme-update --file ./scheme.json |
接口路径是 API 路径，不是本地文件路径。Windows Git Bash 可能会把以 / 开头的参数转换成 D:/... 这样的本地路径。遇到这种情况，建议使用单引号，例如 --path '/api/users'，或使用 --file 提供接口数据。测试用例或场景用例 HTTP 步骤里的 responseId 应填写接口响应定义 endpoint.responses[].id，不能直接填写响应组件 ID。如果要复用响应组件，请先在接口响应定义中通过 referencedResponseId 关联响应组件。
自动化测试#
适用于搭建和运行自动化测试，包括维护单接口测试用例、场景用例、测试套件、测试数据集，以及查看测试报告、Runner 和定时任务。单接口测试用例#
test-case 用于维护自动化测试模块中的单接口测试用例，适用于围绕某个接口配置测试数据、断言和执行参数。| 命令 | 说明 | 示例 |
|---|
test-case list | 列出项目中的单接口测试用例，可按接口过滤。 | apifox test-case list --project <projectId> --endpoint <endpointId> |
test-case category | 列出测试用例分组，用于获取创建或更新时需要的 categoryId。 | apifox test-case category --project <projectId> |
test-case get | 查看单接口测试用例详情。 | apifox test-case get <caseId> --project <projectId> |
test-case create | 从 JSON 文件创建单接口测试用例。 | apifox test-case create --project <projectId> --file ./case.json |
test-case update | 更新单接口测试用例。 | apifox test-case update <caseId> --project <projectId> --file ./case.json |
test-case delete | 删除单接口测试用例。 | apifox test-case delete <caseId> --project <projectId> |
cli-schema get test-case-create | 查看测试用例创建的数据结构。 | apifox cli-schema get test-case-create |
cli-schema validate test-case-create | 校验测试用例创建数据文件。 | apifox cli-schema validate test-case-create --file ./case.json |
cli-schema get test-case-update | 查看测试用例更新的数据结构。 | apifox cli-schema get test-case-update |
cli-schema validate test-case-update | 校验测试用例更新数据文件。 | apifox cli-schema validate test-case-update --file ./case.json |
场景用例#
test-scenario 用于维护自动化测试中的场景用例 。场景用例可包含接口步骤、分组、条件控制等内容，也可直接运行并生成报告。| 命令 | 说明 | 示例 |
|---|
test-scenario list | 列出项目的所有场景用例，用于查找场景用例 ID。 | apifox test-scenario list --project <projectId> |
test-scenario get | 查看场景用例详情，包括步骤结构和运行相关配置。 | apifox test-scenario get <scenarioId> --project <projectId> |
test-scenario create | 创建场景用例。简单场景可用 --name，复杂步骤建议通过数据文件写入。 | apifox test-scenario create --project <projectId> --file ./scenario.json |
test-scenario update | 更新场景用例。更新步骤前建议先查看 cli-schema 并校验数据文件。 | apifox test-scenario update <scenarioId> --project <projectId> --file ./scenario.json |
test-scenario delete | 删除场景用例。 | apifox test-scenario delete <scenarioId> --project <projectId> |
cli-schema get test-scenario-create | 查看场景用例创建的数据结构。 | apifox cli-schema get test-scenario-create |
cli-schema validate test-scenario-create | 校验场景用例创建数据文件。 | apifox cli-schema validate test-scenario-create --file ./scenario.json |
cli-schema get test-scenario-update | 查看场景用例更新的数据结构。 | apifox cli-schema get test-scenario-update |
cli-schema validate test-scenario-update | 校验场景用例更新数据文件。 | apifox cli-schema validate test-scenario-update --file ./scenario.json |
test-scenario run | 运行指定场景用例。运行时通常需要指定环境。 | apifox test-scenario run <scenarioId> --project <projectId> --environment <environmentId> |
测试套件#
test-suite 用于维护测试套件。测试套件可组合多个场景用例或场景目录，适用于回归测试、冒烟测试、发布前验证等批量运行场景。| 命令 | 说明 | 示例 |
|---|
test-suite list | 列出项目的所有测试套件，用于查找套件 ID。 | apifox test-suite list --project <projectId> |
test-suite get | 查看测试套件详情，包括套件内包含的场景或目录配置。 | apifox test-suite get <testSuiteId> --project <projectId> |
test-suite create | 创建测试套件，可关联场景用例或目录。简单套件可用 --name，复杂配置建议通过数据文件写入。 | apifox test-suite create --project <projectId> --file ./suite.json |
test-suite update | 更新测试套件。 | apifox test-suite update <testSuiteId> --project <projectId> --file ./suite.json |
test-suite delete | 删除测试套件。 | apifox test-suite delete <testSuiteId> --project <projectId> |
cli-schema get test-suite-create | 查看测试套件创建的数据结构。 | apifox cli-schema get test-suite-create |
cli-schema validate test-suite-create | 校验测试套件创建数据文件。 | apifox cli-schema validate test-suite-create --file ./suite.json |
cli-schema get test-suite-update | 查看测试套件更新的数据结构。 | apifox cli-schema get test-suite-update |
cli-schema validate test-suite-update | 校验测试套件更新数据文件。 | apifox cli-schema validate test-suite-update --file ./suite.json |
test-suite run | 运行指定测试套件。运行时通常需要指定环境。 | apifox test-suite run <testSuiteId> --project <projectId> --environment <environmentId> |
测试数据#
test-data 用于维护自动化测试模块中的测试数据集，适用于在数据驱动测试中复用多组输入数据。| 命令 | 说明 | 示例 |
|---|
test-data list | 列出自动化测试数据集。 | apifox test-data list --project <projectId> |
test-data get | 查看自动化测试数据集详情。 | apifox test-data get <dataId> --project <projectId> |
test-data create | 从 JSON 文件创建测试数据集。 | apifox test-data create --project <projectId> --file ./test-data.json |
test-data update | 更新测试数据集。 | apifox test-data update <dataId> --project <projectId> --file ./test-data.json |
test-data delete | 删除测试数据集。 | apifox test-data delete <dataId> --project <projectId> |
cli-schema get test-data-create | 查看测试数据集创建的数据结构。 | apifox cli-schema get test-data-create |
cli-schema validate test-data-create | 校验测试数据集创建数据文件。 | apifox cli-schema validate test-data-create --file ./test-data.json |
cli-schema get test-data-update | 查看测试数据集更新的数据结构。 | apifox cli-schema get test-data-update |
cli-schema validate test-data-update | 校验测试数据集更新数据文件。 | apifox cli-schema validate test-data-update --file ./test-data.json |
测试报告#
test-report 用于查看和管理测试运行后生成的报告，支持查看历史运行结果、下载报告文件或清理不再需要的报告。| 命令 | 说明 | 示例 |
|---|
test-report list | 列出项目中的测试报告。 | apifox test-report list --project <projectId> |
test-report get | 查看测试报告详情。 | apifox test-report get <reportId> --project <projectId> |
test-report download | 下载测试报告到本地文件。 | apifox test-report download <reportId> --project <projectId> --format json --output ./report.json |
test-report delete | 删除测试报告。 | apifox test-report delete <reportId> --project <projectId> |
Runner#
runner 用于查看和管理团队或项目中的 Runner。适用于排查运行环境、确认 Runner 状态，或执行健康检查。| 命令 | 说明 | 示例 |
|---|
runner list | 列出项目或团队中的 Runner。 | apifox runner list --project <projectId> |
runner get | 查看 Runner 详情。 | apifox runner get <runnerId> --project <projectId> |
runner create | 创建团队 Runner。 | apifox runner create --team <teamId> --name <name> --runner-type <runnerType> --server-type <serverType> |
runner check | 检查 Runner 健康状态。 | apifox runner check <runnerId> --team <teamId> |
runner delete | 删除 Runner。 | apifox runner delete <runnerId> --project <projectId> |
cli-schema get runner-create | 查看 Runner 创建数据结构。 | apifox cli-schema get runner-create |
cli-schema validate runner-create | 校验 Runner 创建数据文件。 | apifox cli-schema validate runner-create --file ./runner.json |
定时任务#
scheduled-task 用于维护自动化测试定时任务，支持配置计划运行测试，也支持通过 CLI 手动触发任务。| 命令 | 说明 | 示例 |
|---|
scheduled-task list | 列出项目中的定时任务。 | apifox scheduled-task list --project <projectId> |
scheduled-task get | 查看定时任务详情。 | apifox scheduled-task get <taskId> --project <projectId> |
scheduled-task create | 从 JSON 文件创建定时任务。 | apifox scheduled-task create --project <projectId> --file ./scheduled-task.json |
scheduled-task update | 更新定时任务。 | apifox scheduled-task update <taskId> --project <projectId> --file ./scheduled-task.json |
scheduled-task delete | 删除定时任务。 | apifox scheduled-task delete <taskId> --project <projectId> |
scheduled-task run | 手动触发一次定时任务。 | apifox scheduled-task run <taskId> --project <projectId> |
cli-schema get scheduled-task-create | 查看定时任务创建的数据结构。 | apifox cli-schema get scheduled-task-create |
cli-schema validate scheduled-task-create | 校验定时任务创建数据文件。 | apifox cli-schema validate scheduled-task-create --file ./scheduled-task.json |
cli-schema get scheduled-task-update | 查看定时任务更新的数据结构。 | apifox cli-schema get scheduled-task-update |
cli-schema validate scheduled-task-update | 校验定时任务更新数据文件。 | apifox cli-schema validate scheduled-task-update --file ./scheduled-task.json |
核心运行命令：apifox run#
这是 Apifox 功能最丰富用例运行命令。您可以直接从 Apifox 客户端 -> 自动化测试 -> CI/CD 面板中复制生成的命令。常用命令示例 (从客户端复制)#
1. 使用 Access Token 运行在线场景：--upload-report: 执行完后自动同步报告到云端
运行参数表说明#
| 参数 | 描述 | 默认值 |
|---|
--access-token <token> | 设置鉴权令牌 | - |
-t, --test-scenario <id> | 指定场景用例 ID | - |
-f, --test-scenario-folder <id> | 指定 场景用例目录 ID | - |
--test-suite <id> | 指定测试套件 ID | - |
--project <id> | 项目 ID | - |
--branch <branchName> | 指定运行数据所在分支；不传时默认主分支 | - |
-e, --environment <id> | 环境 ID | - |
-r, --reporters [reporters] | 指定报告类型 (cli, html, json, junit) | ["cli"] |
--out-dir <path> | 输出报告目录 | ./apifox-reports |
--out-file <name> | 输出报告文件名（不含后缀）。支持变量: {SCENARIO_NAME}, {FOLDER_NAME}, {GENERATE_TIME} | apifox-report-{timestamp} |
--out-json-failures-separated | 开启 JSON 报告时，将失败详情单独导出 | - |
-n, --iteration-count <n> | 设置循环次数 | - |
-d, --iteration-data <path> | 设置循环数据 (JSON/CSV) 或数据 ID | - |
--on-error <behavior> | 设置错误处理方式 (ignore, continue, end) | - |
--global-var <key=value> | 设置全局变量。支持设置多个。 | - |
--env-var <key=value> | 设置环境变量。支持设置多个。 | - |
--variables <path> | 指定包含变量的本地文件路径 | - |
--notification <ids> | 运行完成后通知指定对象 ID (逗号分隔) | - |
--notification-failed-event <ids> | 仅失败时通知指定对象 ID | - |
--external-program-path <path> | 指定外部脚本/程序的所处目录 | 当前目录 |
--database-connection <path> | 指定数据库配置文件的所处路径 | - |
--ignore-redirects | 阻止自动重定向 | - |
--silent | 开启静默模式，不输出至控制台 | - |
--color <on|off|auto> | 控制台彩色输出开关 | auto |
--delay-request [ms] | 请求之间的停顿间隔 | 0 |
--timeout-request [ms] | 接口请求超时时间 | 0 |
--timeout-script [ms] | 脚本执行超时时间 | 0 |
-k, --insecure | 关闭 SSL 校验 | - |
--ssl-client-cert-list <path> | 指定客户端证书配置路径 (JSON) | - |
--upload-report | 将本次测试报告上传至云端查看 | - |
-b, --bigint | 兼容 BigInt 类型 | false |
--lang <zh |en> | 设置 CLI 语言 | zh |
创建或更新场景用例、测试套件、测试用例、测试数据集、定时任务等复杂测试资源时，建议先执行 cli-schema get <schemaKey>，再执行 cli-schema validate <schemaKey> --file <path>，校验通过后再写入。
导入&导出#
适用于将外部接口文档导入 Apifox，或将项目数据导出为其他工具可使用的格式。CLI 通过 --format 指定导入或导出格式，并支持维护自动导入和 OAS 导出设置。导入项目数据#
import 用于把本地文件导入到指定项目。当前 --format 支持以下值：openapi、postman、har、insomnia、jmeter、wsdl、yapi、rap2、apidoc、hoppscotch、markdown、jsonschema、apifox。| 命令 | 说明 | 示例 |
|---|
import | 将本地文件按指定格式导入到项目。 | apifox import --project <projectId> --format openapi --file ./openapi.json |
自动导入设置#
import auto-import 用于维护自动导入设置。适用于从外部源长期同步接口数据，可配置导入来源和同步规则。| 命令 | 说明 | 示例 |
|---|
import auto-import list | 列出项目中的自动导入设置。 | apifox import auto-import list --project <projectId> |
import auto-import create | 创建自动导入设置。 | apifox import auto-import create --project <projectId> --file ./auto-import.json |
import auto-import get | 查看自动导入设置详情。 | apifox import auto-import get <settingId> --project <projectId> |
import auto-import delete | 删除自动导入设置。 | apifox import auto-import delete <settingId> --project <projectId> |
cli-schema get import-auto-import-create | 查看自动导入设置创建所需的 JSON Schema。 | apifox cli-schema get import-auto-import-create |
cli-schema validate import-auto-import-create | 校验自动导入设置数据文件。 | apifox cli-schema validate import-auto-import-create --file ./auto-import.json |
导出项目数据#
export 用于把项目数据导出到本地文件。当前 --format 支持以下值：openapi、markdown、html、postman。| 命令 | 说明 | 示例 |
|---|
export | 将项目数据按指定格式导出为本地文件。 | apifox export --project <projectId> --format openapi --output ./openapi.json |
OAS 导出设置#
export settings 用于维护 OAS 导出设置。适用于按固定规则反复导出 OpenAPI 文档的场景，可保存配置并复用。| 命令 | 说明 | 示例 |
|---|
export settings list | 列出项目中的 OAS 导出设置。 | apifox export settings list --project <projectId> |
export settings create | 创建 OAS 导出设置。 | apifox export settings create --project <projectId> --file ./export-setting.json |
export settings get | 查看 OAS 导出设置详情。 | apifox export settings get <settingId> --project <projectId> |
export settings update | 更新 OAS 导出设置。 | apifox export settings update <settingId> --project <projectId> --file ./export-setting.json |
export settings delete | 删除 OAS 导出设置。 | apifox export settings delete <settingId> --project <projectId> |
cli-schema get export-settings-create | 查看 OAS 导出设置创建所需的 JSON Schema。 | apifox cli-schema get export-settings-create |
cli-schema validate export-settings-create | 校验 OAS 导出设置数据文件。 | apifox cli-schema validate export-settings-create --file ./export-setting.json |
cli-schema get export-settings-update | 查看 OAS 导出设置更新所需的 JSON Schema。 | apifox cli-schema get export-settings-update |
cli-schema validate export-settings-update | 校验 OAS 导出设置更新数据文件。 | apifox cli-schema validate export-settings-update --file ./export-setting.json |
分享文档#
适用于管理接口文档的发布与分享入口，包括面向团队成员、外部协作者或调用方的文档站和在线文档。文档站#
docs-site 用于维护文档站。文档站可将整个项目或指定范围的接口文档以站点形式发布，并支持域名、导航、外观、可见性等站点级配置。| 命令 | 说明 | 示例 |
|---|
docs-site list | 列出项目中的文档站。 | apifox docs-site list --project <projectId> |
docs-site get | 查看文档站详情。 | apifox docs-site get <siteId> --project <projectId> |
docs-site create | 创建文档站。 | apifox docs-site create --project <projectId> --file ./docs-site-create.json |
docs-site update | 更新文档站配置。 | apifox docs-site update <siteId> --project <projectId> --file ./docs-site-update.json |
docs-site delete | 删除文档站。 | apifox docs-site delete <siteId> --project <projectId> |
cli-schema get docs-site-create | 查看文档站创建所需的 JSON Schema。 | apifox cli-schema get docs-site-create |
cli-schema validate docs-site-create | 校验文档站数据文件是否符合 Schema。 | apifox cli-schema validate docs-site-create --file ./docs-site.json |
cli-schema get docs-site-update | 查看文档站更新所需的 JSON Schema。 | apifox cli-schema get docs-site-update |
cli-schema validate docs-site-update | 校验文档站更新数据文件是否符合 Schema。 | apifox cli-schema validate docs-site-update --file ./docs-site-update.json |
在线文档#
shared-doc 用于维护在线文档分享。可为选定接口或文档内容生成共享链接，并配置密码、有效期、环境、语言等分享设置，适用于按范围分享部分文档内容。| 命令 | 说明 | 示例 |
|---|
shared-doc list | 列出在线文档。 | apifox shared-doc list --project <projectId> |
shared-doc get | 查看在线文档详情。 | apifox shared-doc get <docId> --project <projectId> |
shared-doc create | 创建在线文档。 | apifox shared-doc create --project <projectId> --file ./shared-doc.json |
shared-doc update | 更新在线文档配置。 | apifox shared-doc update <docId> --project <projectId> --file ./shared-doc-update.json |
shared-doc delete | 删除在线文档。 | apifox shared-doc delete <docId> --project <projectId> |
cli-schema get shared-doc-create | 查看在线文档创建所需的 JSON Schema。 | apifox cli-schema get shared-doc-create |
cli-schema validate shared-doc-create | 校验在线文档数据文件是否符合 Schema。 | apifox cli-schema validate shared-doc-create --file ./shared-doc.json |
cli-schema get shared-doc-update | 查看在线文档更新所需的 JSON Schema。 | apifox cli-schema get shared-doc-update |
cli-schema validate shared-doc-update | 校验在线文档更新数据文件是否符合 Schema。 | apifox cli-schema validate shared-doc-update --file ./shared-doc-update.json |
分支管理#
适用于多人协作或按版本维护接口，通过分支隔离不同阶段的改动。CLI 支持管理迭代分支、AI 分支、通用分支、直接合并和合并请求，并支持在合并前扫描候选改动，以确认可能合入目标分支的资源。分支合并有两种常见方式：未受保护的目标分支可使用 branch merge 直接合并；受保护主分支通常使用 merge-request 创建合并请求并走审核流程。branch merge 只会合并显式传入的资源清单，不会默认合并整个分支。迭代分支#
branch --type sprint 用于维护普通迭代分支。创建迭代分支时建议指定来源分支；不传 --branch 操作项目资源时，后端默认使用主分支。| 命令 | 说明 | 示例 |
|---|
branch list --type all | 列出项目中的所有分支类型。all 仅用于 list。 | apifox branch list --project <projectId> --type all |
branch list --type sprint | 列出项目中的普通迭代分支。 | apifox branch list --project <projectId> --type sprint |
branch get --type sprint | 查看普通迭代分支详情。 | apifox branch get <branchName> --project <projectId> --type sprint |
branch create --type sprint | 创建普通迭代分支。 | apifox branch create --project <projectId> --type sprint --name "新分支名" --from main |
branch update --type sprint | 更新分支名称或主分支保护设置。 | apifox branch update <branchName> --project <projectId> --type sprint --name 新分支名 |
branch merge | 直接合并分支，只会合并显式传入的资源清单，不会自动补引用资源或目录资源。 | apifox branch merge --project <projectId> --from <sourceBranchName> --to <targetBranchName> --endpoint-ids <ids> |
branch pick-to | 从源分支导入资源到目标分支，常用于把源分支已有资源导入 AI 分支后再编辑。 | apifox branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids> |
branch archive --type sprint | 归档普通迭代分支。删除前必须先归档。 | apifox branch archive <branchName> --project <projectId> --type sprint |
branch delete --type sprint | 删除已归档的普通迭代分支。 | apifox branch delete <branchName> --project <projectId> --type sprint |
cli-schema get branch-sprint-create | 查看迭代分支创建所需的数据结构。 | apifox cli-schema get branch-sprint-create |
cli-schema get branch-sprint-update | 查看迭代分支更新所需的数据结构。 | apifox cli-schema get branch-sprint-update |
AI 分支#
branch --type ai 用于维护 AI 分支。AI 分支适合让 AI Agent 或自动化流程隔离修改项目资源，完成后再由用户确认是否合并或发起合并请求。| 命令 | 说明 | 示例 |
|---|
branch list --type ai | 列出项目中的 AI 分支。 | apifox branch list --project <projectId> --type ai |
branch get --type ai | 查看 AI 分支详情。 | apifox branch get <branchName> --project <projectId> --type ai |
branch create --type ai | 创建 AI 分支，并指定来源分支。 | apifox branch create --project <projectId> --type ai --name <aiBranchName> --from <sourceBranchName> |
branch update --type ai | 更新 AI 分支名称。 | apifox branch update <branchName> --project <projectId> --type ai --name <newName> |
branch archive --type ai | 归档 AI 分支。删除前必须先归档。 | apifox branch archive <branchName> --project <projectId> --type ai |
branch delete --type ai | 删除已归档的 AI 分支。 | apifox branch delete <branchName> --project <projectId> --type ai |
cli-schema get branch-ai-create | 查看 AI 分支创建所需的数据结构。 | apifox cli-schema get branch-ai-create |
cli-schema get branch-ai-update | 查看 AI 分支更新所需的数据结构。 | apifox cli-schema get branch-ai-update |
通用分支#
branch --type general 用于管理通用分支，适用于按通用版本组织项目内容。通用分支只承载普通版本，不提供 AI 分支能力，也不能作为 AI 分支的来源分支。| 命令 | 说明 | 示例 |
|---|
branch list --type general | 列出项目中的通用分支。 | apifox branch list --project <projectId> --type general |
branch get --type general | 查看通用分支详情。 | apifox branch get <branchName> --project <projectId> --type general |
branch create --type general | 创建通用分支。 | apifox branch create --project <projectId> --type general --name "New Version" --from main |
branch update --type general | 更新通用分支。 | apifox branch update <branchName> --project <projectId> --type general --name <newName> |
branch delete --type general | 删除通用分支。 | apifox branch delete <branchName> --project <projectId> --type general |
cli-schema get branch-general-create | 查看通用分支创建所需的数据结构。 | apifox cli-schema get branch-general-create |
cli-schema get branch-general-update | 查看通用分支更新所需的数据结构。 | apifox cli-schema get branch-general-update |
分支创建命令主要通过命令行参数传入，例如 --type、--name、--from。cli-schema get branch-*-create 用于查看创建参数结构，实际创建命令请以 apifox branch create -h 为准。branch merge 和 branch pick-to 的资源 ID 参数使用复数形式，并传入逗号分隔的数字 ID，例如 --endpoint-ids 1,2、--doc-ids 3,4、--test-suite-ids 5,6。
合并请求#
merge-request 用于受保护主分支的合并请求。未受保护的目标分支通常使用 branch merge 直接合并；需要审核流程时，再创建合并请求。创建合并请求时，需要明确选择要合并的资源；Apifox 只合并显式传入的资源，不会自动补引用资源或目录资源。| 命令 | 说明 | 示例 |
|---|
merge-request preview | 创建合并请求或直接合并前，扫描 CLI 当前支持资源类型的候选差异。此命令不是完整资源 diff，正式合并前仍建议手动确认。 | apifox merge-request preview --project <projectId> --from <sourceBranchName> --to <targetBranchName> |
merge-request list | 列出合并请求。 | apifox merge-request list --project <projectId> --to <targetBranchName> |
merge-request get | 查看合并请求详情。 | apifox merge-request get <mergeRequestId> --project <projectId> --to <targetBranchName> |
merge-request create | 创建合并请求。 | apifox merge-request create --project <projectId> --to <targetBranchName> --from <sourceBranchName> --reviewer-ids <userIds> --endpoint-ids <ids> |
merge-request update | 更新合并请求。 | apifox merge-request update <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./merge-request.json |
merge-request approve | 批准合并请求。 | apifox merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json |
merge-request reject | 拒绝合并请求。 | apifox merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName> |
merge-request delete | 删除合并请求。 | apifox merge-request delete <mergeRequestId> --project <projectId> --to <targetBranchName> |
cli-schema get merge-request-create | 查看合并请求创建所需的 JSON Schema。 | apifox cli-schema get merge-request-create |
cli-schema validate merge-request-create | 校验合并请求创建数据文件。 | apifox cli-schema validate merge-request-create --file ./merge-request.json |
cli-schema get merge-request-update | 查看合并请求更新所需的 JSON Schema。 | apifox cli-schema get merge-request-update |
cli-schema validate merge-request-update | 校验合并请求更新数据文件。 | apifox cli-schema validate merge-request-update --file ./merge-request.json |
cli-schema get merge-request-approve | 查看批准合并请求所需的 JSON Schema。 | apifox cli-schema get merge-request-approve |
cli-schema validate merge-request-approve | 校验批准合并请求数据文件。 | apifox cli-schema validate merge-request-approve --file ./approve.json |
1.
为了确保项目资源安全，CLI 默认写入权限受限制，您可以基于 AI 分支编辑来源分支数据，或在 项目设置 -> 功能设置 -> AI 功能设置 -> 外部 AI 编辑权限 中按需开启：主分支、标准迭代分支和通用分支的直接编辑权限。AI 分支修改完成后仍需用户确认，再发起 merge 或 merge-request。
2.
AI 分支推荐命名为 ai/年月日-from-来源分支名-功能或模块名，例如 ai/20260312-from-main-userRegister。
其他资源#
适用于维护项目扩展资源和外部连接配置，包括自定义字段、WebSocket / Socket.IO 接口、脚本库公共脚本、数据库连接、密钥库提供方和 Git 连接。自定义字段#
custom-field 用于维护项目自定义字段，适用于为接口、文档或其他资源补充团队自定义属性。| 命令 | 说明 | 示例 |
|---|
custom-field list | 列出自定义字段。 | apifox custom-field list --project <projectId> |
custom-field create | 创建自定义字段。 | apifox custom-field create --project <projectId> --file ./custom-field.json |
custom-field update | 更新自定义字段。 | apifox custom-field update <customFieldId> --project <projectId> --file ./custom-field.json |
custom-field delete | 删除自定义字段。 | apifox custom-field delete <customFieldId> --project <projectId> |
cli-schema get custom-field-create | 查看自定义字段创建所需的 JSON Schema。 | apifox cli-schema get custom-field-create |
cli-schema validate custom-field-create | 校验自定义字段创建数据文件。 | apifox cli-schema validate custom-field-create --file ./custom-field.json |
cli-schema get custom-field-update | 查看自定义字段更新所需的 JSON Schema。 | apifox cli-schema get custom-field-update |
cli-schema validate custom-field-update | 校验自定义字段更新数据文件。 | apifox cli-schema validate custom-field-update --file ./custom-field.json |
WebSocket 接口#
websocket 用于维护项目中的 WebSocket 接口，适用于管理需要长连接通信的实时接口。| 命令 | 说明 | 示例 |
|---|
websocket list | 列出项目中的 WebSocket 接口。 | apifox websocket list --project <projectId> |
websocket get | 查看 WebSocket 接口详情。 | apifox websocket get <websocketId> --project <projectId> |
websocket create | 创建 WebSocket 接口。 | apifox websocket create --project <projectId> --name <name> --url <url> |
websocket update | 更新 WebSocket 接口。 | apifox websocket update <websocketId> --project <projectId> --file ./websocket.json |
websocket delete | 删除 WebSocket 接口。 | apifox websocket delete <websocketId> --project <projectId> |
cli-schema get websocket-create | 查看 WebSocket 接口创建所需的 JSON Schema。 | apifox cli-schema get websocket-create |
cli-schema validate websocket-create | 校验 WebSocket 接口创建数据文件。 | apifox cli-schema validate websocket-create --file ./websocket.json |
cli-schema get websocket-update | 查看 WebSocket 接口更新所需的 JSON Schema。 | apifox cli-schema get websocket-update |
cli-schema validate websocket-update | 校验 WebSocket 接口更新数据文件。 | apifox cli-schema validate websocket-update --file ./websocket.json |
Socket.IO 接口#
socketio 用于维护项目中的 Socket.IO 接口，适用于管理基于 Socket.IO 协议的实时通信接口。| 命令 | 说明 | 示例 |
|---|
socketio list | 列出项目中的 Socket.IO 接口。 | apifox socketio list --project <projectId> |
socketio get | 查看 Socket.IO 接口详情。 | apifox socketio get <socketioId> --project <projectId> |
socketio create | 创建 Socket.IO 接口。简单接口可用 --name/--url；复杂事件、请求体、参数和高级设置使用 --file。 | apifox socketio create --project <projectId> --file ./socketio.json |
socketio update | 更新 Socket.IO 接口。 | apifox socketio update <socketioId> --project <projectId> --file ./socketio.json |
socketio delete | 删除 Socket.IO 接口。 | apifox socketio delete <socketioId> --project <projectId> |
cli-schema get socketio-create | 查看 Socket.IO 接口创建所需的 JSON Schema。 | apifox cli-schema get socketio-create |
cli-schema validate socketio-create | 校验 Socket.IO 接口创建数据文件。 | apifox cli-schema validate socketio-create --file ./socketio.json |
cli-schema get socketio-update | 查看 Socket.IO 接口更新所需的 JSON Schema。 | apifox cli-schema get socketio-update |
cli-schema validate socketio-update | 校验 Socket.IO 接口更新数据文件。 | apifox cli-schema validate socketio-update --file ./socketio.json |
脚本库公共脚本#
common-script 用于维护脚本库公共脚本。适用于多个接口、场景用例或前后置脚本复用同一段脚本逻辑的场景。| 命令 | 说明 | 示例 |
|---|
common-script list | 列出脚本库公共脚本。 | apifox common-script list --project <projectId> |
common-script get | 查看脚本库公共脚本详情。 | apifox common-script get <scriptId> --project <projectId> |
common-script create | 创建脚本库公共脚本。简单脚本可用 --name/--content；需要 description 或 runMode 时使用 --file，runMode 仅支持 independent / merge。 | apifox common-script create --project <projectId> --file ./common-script.json |
common-script update | 更新脚本库公共脚本。 | apifox common-script update <scriptId> --project <projectId> --file ./common-script.json |
common-script delete | 删除脚本库公共脚本。 | apifox common-script delete <scriptId> --project <projectId> |
cli-schema get common-script-create | 查看脚本库公共脚本创建所需的 JSON Schema。 | apifox cli-schema get common-script-create |
cli-schema validate common-script-create | 校验脚本库公共脚本创建数据文件。 | apifox cli-schema validate common-script-create --file ./common-script.json |
cli-schema get common-script-update | 查看脚本库公共脚本更新所需的 JSON Schema。 | apifox cli-schema get common-script-update |
cli-schema validate common-script-update | 校验脚本库公共脚本更新数据文件。 | apifox cli-schema validate common-script-update --file ./common-script.json |
数据库连接资源#
database-connection 用于维护项目中的数据库连接信息。自动化测试运行时如需读取本地数据库配置，仍需在 apifox run 中配合 --database-connection 指定配置文件。| 命令 | 说明 | 示例 |
|---|
database-connection list | 列出项目中的数据库连接。 | apifox database-connection list --project <projectId> |
database-connection get | 查看数据库连接详情。 | apifox database-connection get <connectionId> --project <projectId> |
database-connection create | 创建数据库连接。简单连接可用 --name/--type/--host；包含端口、账号、密码、SSH、SSL 或环境差异配置时使用 --file。 | apifox database-connection create --project <projectId> --file ./database-connection.json |
database-connection update | 更新数据库连接。 | apifox database-connection update <connectionId> --project <projectId> --file ./database-connection.json |
database-connection delete | 删除数据库连接。 | apifox database-connection delete <connectionId> --project <projectId> |
cli-schema get database-connection-create | 查看数据库连接创建所需的 JSON Schema。 | apifox cli-schema get database-connection-create |
cli-schema validate database-connection-create | 校验数据库连接创建数据文件。 | apifox cli-schema validate database-connection-create --file ./database-connection.json |
cli-schema get database-connection-update | 查看数据库连接更新所需的 JSON Schema。 | apifox cli-schema get database-connection-update |
cli-schema validate database-connection-update | 校验数据库连接更新数据文件。 | apifox cli-schema validate database-connection-update --file ./database-connection.json |
密钥库提供方#
vault 用于维护密钥库提供方，适用于项目从外部密钥服务读取敏感配置的场景。| 命令 | 说明 | 示例 |
|---|
vault list | 列出密钥库提供方。 | apifox vault list --project <projectId> |
vault get | 查看密钥库提供方详情。 | apifox vault get <vaultProviderId> --project <projectId> |
vault create | 创建密钥库提供方。 | apifox vault create --project <projectId> --file ./vault.json |
vault update | 更新密钥库提供方。 | apifox vault update <vaultProviderId> --project <projectId> --file ./vault.json |
vault delete | 删除密钥库提供方。 | apifox vault delete <vaultProviderId> --project <projectId> |
cli-schema get vault-create | 查看密钥库提供方创建所需的 JSON Schema。 | apifox cli-schema get vault-create |
cli-schema validate vault-create | 校验密钥库提供方创建数据文件。 | apifox cli-schema validate vault-create --file ./vault.json |
cli-schema get vault-update | 查看密钥库提供方更新所需的 JSON Schema。 | apifox cli-schema get vault-update |
cli-schema validate vault-update | 校验密钥库提供方更新数据文件。 | apifox cli-schema validate vault-update --file ./vault.json |
Git 连接#
git-connection 用于维护项目和代码仓库之间的 Git 连接，适用于将接口文档与代码仓库关联的场景。| 命令 | 说明 | 示例 |
|---|
git-connection list | 列出项目中的 Git 连接。 | apifox git-connection list --project <projectId> |
git-connection get | 查看 Git 连接详情。 | apifox git-connection get <connectionId> --project <projectId> |
git-connection create | 创建 Git 连接。 | apifox git-connection create --project <projectId> --file ./git-connection.json |
git-connection update | 更新 Git 连接。前后端支持更新名称、描述、类型、configs 和 refreshToken。 | apifox git-connection update <connectionId> --project <projectId> --file ./git-connection.json |
git-connection delete | 删除 Git 连接。 | apifox git-connection delete <connectionId> --project <projectId> |
cli-schema get git-connection-create | 查看 Git 连接创建所需的 JSON Schema。 | apifox cli-schema get git-connection-create |
cli-schema validate git-connection-create | 校验 Git 连接创建数据文件。 | apifox cli-schema validate git-connection-create --file ./git-connection.json |
cli-schema get git-connection-update | 查看 Git 连接更新所需的 JSON Schema。 | apifox cli-schema get git-connection-update |
cli-schema validate git-connection-update | 校验 Git 连接更新数据文件。 | apifox cli-schema validate git-connection-update --file ./git-connection.json |
管理与设置#
适用于项目日常管理，包括配置通知、恢复或删除项目内回收站资源、查看变更历史，以及排查成员操作记录。通知配置#
notification 用于维护项目通知配置。运行测试时可通过通知参数触发通知；本命令用于管理 项目中保存的通知配置。| 命令 | 说明 | 示例 |
|---|
notification list | 列出项目中的通知配置。 | apifox notification list --project <projectId> |
notification get | 查看通知配置详情。 | apifox notification get <notificationId> --project <projectId> |
notification create | 创建通知配置。 | apifox notification create --project <projectId> --file ./notification.json |
notification update | 更新通知配置。 | apifox notification update <notificationId> --project <projectId> --file ./notification.json |
notification delete | 删除通知配置。 | apifox notification delete <notificationId> --project <projectId> |
cli-schema get notification-create | 查看通知配置创建所需的 JSON Schema。 | apifox cli-schema get notification-create |
cli-schema validate notification-create | 校验通知配置创建数据文件。 | apifox cli-schema validate notification-create --file ./notification.json |
cli-schema get notification-update | 查看通知配置更新所需的 JSON Schema。 | apifox cli-schema get notification-update |
cli-schema validate notification-update | 校验通知配置更新数据文件。 | apifox cli-schema validate notification-update --file ./notification.json |
回收站#
recycle 用于处理项目内回收站资源，支持查看、恢复或永久删除已进入回收站的资源。| 命令 | 说明 | 示例 |
|---|
recycle list | 列出项目内回收站资源。 | apifox recycle list --project <projectId> |
recycle restore | 从回收站恢复资源。 | apifox recycle restore <itemId> --project <projectId> |
recycle delete | 永久删除回收站资源。 | apifox recycle delete <itemId> --project <projectId> |
变更历史#
history 用于查看项目已 有变更历史，适用于排查资源修改时间以及追踪历史记录，不建议作为刚刚写入操作是否成功的唯一验证方式。| 命令 | 说明 | 示例 |
|---|
history list | 列出项目中的变更历史。 | apifox history list --project <projectId> |
history get | 查看变更历史详情。 | apifox history get <historyId> --project <projectId> |
审计日志#
audit-log 用于查看项目审计日志，适用于安全审计或排查成员操作记录，不保证覆盖所有资源写入的即时验证。| 命令 | 说明 | 示例 |
|---|
audit-log list | 列出项目中的审计日志。 | apifox audit-log list --project <projectId> |
audit-log get | 查看审计日志详情。 | apifox audit-log get <auditLogId> --project <projectId> |
高级操作#
适用于 CLI 运行过程中的进阶配置，包括文件上传、数据库配置、报告上传、外部脚本以及 SSL / HTTP/2 等能力。CLI 中的文件上传#
涉及文件上传的接口在 CLI 中运行时，需要确保文件存在于运行 CLI 的机器上。Apifox 仅保存本地文件路径，不会同步文件本身；如果在其他机器上运行同一场景用例，原本的本地路径可能无法访问。1
将需要上传的文件复制或上传到运行 CLI 的机器。
2
记录该文件在运行机器上的路径，例如：
/var/www/myapp/uploads/apifox-xiangmu.jpg
3
在 Apifox 自动化测试中定位到需要上传文件的接口，点击“批量编辑”按钮。
4
将运行 CLI 机器上的文件路径填入“参数值”。
5
也可以将文件路径配置到环境变量的“远程值”中，并在“批量编辑”中通过变量引用。
如需在本地再次运行该场景用例，请将参数值中的文件路径改回本地机器可访问的路径。
CLI 中的数据库操作#
当场景用例包含数据库操作时，由于数据库配置保存在本地而非云端，需要在运行 CLI 前准备数据库配置文件。1
对于包含数据库操作的场景用例，在命令行生成界面点击“下载数据库配置文件”。
2
下载配置文件（如 database-connections.json），并放置到运行 CLI 的目录下。
3
在运行命令中加入
--database-connection 选项。示例：
将本地 CLI 测试报告上传到云端#
可通过 --upload-report 参数将本地 CLI 测试报告上传到云端。2
上传完成后，可在以下位置查看报告：
打开 Apifox 自动化测试面板中的 “测试报告”
CLI 中使用外部脚本/程序#
可通过 --external-program-path 引用外部脚本：在该示例中，CLI 会引用 ./scripts 目录下的程序。未指定时，默认使用当前 CLI 执行目录。1.
本地路径：建议按类别整理脚本文件，放在特定目录下并在 CLI 命令中指定。
2.
云端代码仓库：在 CI/CD 工作流中先拉取脚本到本地，再在 CLI 命令中指定实际路径。
SSL#
使用单个 SSL 客户端证书#
使用 SSL 客户端证书配置文件（支持多个证书）#
指定 SSL 客户端证书列表的 JSON 文件路径。例如：ssl-client-cert-list.jsonssl-client-cert-list.json
[
{
"name": "domain1",
"matches": ["https://test.domain1.com/*", "https://www.domain1/*"],
"key": {"src": "./client.domain1.key"},
"cert": {"src": "./client.domain1.crt"},
"passphrase": "changeme"
},
{
"name": "domain2",
"matches": ["https://domain2.com/*"],
"key": {"src": "./client.domain2.key"},
"cert": {"src": "./client.domain2.crt"},
"passphrase": "changeme"
}
]
--ssl-client-cert、--ssl-client-key 和 --ssl-client-passphrase 选项。如果 URL 在列表中没有匹配项，会使用这些选项作为后备选项。HTTP/2#
CLI 可以通过 --preferred-http-version 参数配置使用特定的协议版本发送请求。1.
"HTTP/2" - HTTP/2 应用层协议协商（ALPN），仅支持 HTTPS 请求
2.
"HTTP/2-with-prior-knowledge" - 已知的 HTTP/2
1.
为 HTTPS 和 HTTP 请求设置不同的协议版本：--preferred-http-version="https=HTTP/2,http=HTTP/2-with-prior-knowledge"
2.
为 HTTPS 和 HTTP 设置相同的协议版本：--preferred-http-version="HTTP/1"
3.
为 HTTPS 和 HTTP 设置 HTTP/2（不支持的值会自动忽略）：--preferred-http-version="HTTP/2"
常见问题 (FAQ)#
该错误通常由 Authorization 请求 头中包含非法字符导致，例如中文、换行符或多余空格。请确认 Authorization 的值不包含中文或特殊符号，并符合预期格式。
在 Apifox 项目内：项目设置 -> 功能设置 -> AI 功能设置 -> 外部 AI 编辑权限 中按需开启：主分支、标准迭代分支和通用分支的直接编辑权限。
