apifox-cli-checkup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI 使用检查与版本确认

CLI Usage Check and Version Verification

前置条件：先阅读
../apifox-cli/SKILL.md
。若旧总入口与本 skill 的规则冲突，以当前
apifox <command> --help
和本 skill 为准。根据资源类型再读取对应业务 skill。

本 skill 用于公开 CLI 使用排查，不依赖内部接口或内部代码。目标是确认命令、项目、分支、环境、资源 ID、报告位置和 CLI 版本是否一致，再回到具体业务 skill 修正资源结构。Agent 排查时优先以当前 help、schema validate、get 回读和 agentHints 组成闭环，不要只看 summary 文案。

Prerequisite: Read
../apifox-cli/SKILL.md
first. If there is a conflict between the old main entry and the rules of this skill, follow the current
apifox <command> --help
and this skill. Read the corresponding business skill according to the resource type.

This skill is used for public CLI troubleshooting and does not rely on internal interfaces or code. The goal is to verify consistency of commands, projects, branches, environments, resource IDs, report locations, and CLI versions, then return to the specific business skill to correct the resource structure. When troubleshooting with Agent, prioritize forming a closed loop with current help, schema validate, get readback, and agentHints instead of relying solely on summary copy.

何时使用

When to Use

CLI 返回成功，但 Apifox 页面没看到资源或展示不完整。
创建后
```
list/get
```
找不到资源。
测试用例、测试场景或测试套件运行失败。
本地报告或云端报告找不到、没有步骤详情。
```
agentHints
```
、help、示例或实际命令行为互相矛盾。
用户或测试同学反馈“我这边没有这个参数”“命令不认识”，需要确认 CLI 版本。

CLI returns success, but the resource is not visible or displayed incompletely on the Apifox page.
The resource cannot be found via
```
list/get
```
after creation.
Test cases, test scenarios, or test suites fail to run.
Local or cloud reports are missing or lack step details.
```
agentHints
```
, help, examples, or actual command behavior contradict each other.
Users or testers report "I don't have this parameter" or "The command is unrecognized", and you need to verify the CLI version.

先做 5 件事

First 5 Actions

记录原始命令、projectId、branch、resourceId、environmentId、文件路径和是否带
```
--api-base-url
```
。
执行
```
apifox --version
```
，确认本机 CLI 版本；参数不存在时先看是否需要更新。
执行对应
```
apifox <command> --help
```
，以当前公开 help 为准，不凭旧文档或记忆使用参数。
用对应
```
list/get
```
回读资源，确认是否写入了预期项目、分支、模块、目录或分类。
如果是运行或报告问题，先区分本地报告和云端报告：未带
```
--upload-report
```
时，不要去云端报告列表找本次结果。

Record the original command, projectId, branch, resourceId, environmentId, file path, and whether
```
--api-base-url
```
is included.
Execute
```
apifox --version
```
to confirm the local CLI version; if parameters are missing, first check if an update is needed.
Execute the corresponding
```
apifox <command> --help
```
, follow the current public help instead of using parameters based on old documents or memory.
Use the corresponding
```
list/get
```
to read back the resource and confirm if it has been written to the expected project, branch, module, directory, or category.
For run or report issues, first distinguish between local and cloud reports: if
```
--upload-report
```
is not included, do not look for the result in the cloud report list.

版本检查

Version Check

先看版本和命令 help：

bash

apifox --version
apifox import --help
apifox test-case category --help

如果测试说明里要求的新参数没有出现在 help 中，优先更新 CLI：

bash

apifox update

非交互环境或确认直接更新时：

bash

apifox update --yes

如果自动更新提示影响排查，可以让用户在 shell 配置里设置禁用每日检查，但这不会影响手动

apifox update

：

bash

export APIFOX_CLI_DISABLE_UPDATE_CHECK=1

版本排查结论必须写清：当前

apifox --version

、命令路径（如

which apifox

）、缺失的参数名、建议更新方式。

First check the version and command help:

bash

apifox --version
apifox import --help
apifox test-case category --help

If the new parameters required in the test instructions do not appear in the help, prioritize updating the CLI:

bash

apifox update

For non-interactive environments or when confirming direct updates:

bash

apifox update --yes

If automatic update prompts interfere with troubleshooting, users can disable daily checks in shell configuration, which does not affect manual

apifox update

bash

export APIFOX_CLI_DISABLE_UPDATE_CHECK=1

The version troubleshooting conclusion must clearly state: current

apifox --version

, command path (e.g.,

which apifox

), missing parameter name, and recommended update method.

help 与提示冲突

Conflict Between Help and Hints

公开文档、agentHints、历史示例和实际行为不一致时，优先以当前
```
apifox <command> --help
```
和实测为准。
不主动推荐 help 未公开的隐藏别名。
```
success=false
```
时以真实
```
success
```
字段和退出码为准，不要相信 summary 里的成功语义。
如果命令提示下一步但实际参数不存在，记录为 CLI 提示问题，并使用 help 中公开的替代命令。

When public documents, agentHints, historical examples, and actual behavior are inconsistent, prioritize the current
```
apifox <command> --help
```
and actual tests.
Do not actively recommend hidden aliases not disclosed in help.
When
```
success=false
```
, rely on the real
```
success
```
field and exit code instead of the success semantics in the summary.
If the command prompts the next step but the actual parameter does not exist, record it as a CLI prompt issue and use the alternative command disclosed in help.

页面看不到资源

Resource Not Visible on Page

优先检查：

是否写入了正确 project。
是否带了正确
```
--branch
```
。
是否资源在 AI 分支中，且页面当前查看的是同一分支。
是否写入到了预期模块或目录。
测试用例是否使用了有效
```
categoryId
```
。
Apifox 原生格式二次导入时，是否因为模块策略导致资源进入了新模块。

常用回读命令：

bash

apifox endpoint list --project <projectId> --branch <branchName>
apifox test-case list --project <projectId> --endpoint <endpointId> --branch <branchName>
apifox test-scenario get <scenarioId> --project <projectId> --branch <branchName> --with-case-detail

如果

get/list

能看到，但页面看不到，先确认页面筛选条件、分支、模块、目录、分类是否一致；不要直接重建资源。

Prioritize checking:

Whether it is written to the correct project.
Whether the correct
```
--branch
```
is included.
Whether the resource is in an AI branch and the page is viewing the same branch.
Whether it is written to the expected module or directory.
Whether the test case uses a valid
```
categoryId
```
.
When re-importing Apifox native format, whether the resource enters a new module due to module policies.

Common readback commands:

bash

apifox endpoint list --project <projectId> --branch <branchName>
apifox test-case list --project <projectId> --endpoint <endpointId> --branch <branchName>
apifox test-scenario get <scenarioId> --project <projectId> --branch <branchName> --with-case-detail

If the resource is visible via

get/list

but not on the page, first confirm that the page filter conditions, branch, module, directory, and category are consistent; do not directly rebuild the resource.

测试用例排查

Test Case Troubleshooting

创建前必须用

apifox test-case category --project <projectId>

获取有效

categoryId

。

当前

test-case category

不支持

--endpoint

；按接口查看用例用

test-case list --endpoint <endpointId>

。

```
test-case get
```
能看到结构，只说明资源已保存，不代表 requestBody、断言、提取变量和脚本一定能运行。
运行失败时检查 environment、变量、请求体、前后置脚本、断言和报告详情。

Must obtain a valid

categoryId

using

apifox test-case category --project <projectId>

before creation.

The current

test-case category

does not support

--endpoint

; use

test-case list --endpoint <endpointId>

to view cases by endpoint.

The fact that
```
test-case get
```
shows the structure only indicates the resource has been saved, not that the requestBody, assertions, extracted variables, and scripts can run correctly.
When execution fails, check the environment, variables, request body, pre/post scripts, assertions, and report details.

测试场景排查

Test Scenario Troubleshooting

```
test-scenario create
```
只创建场景元数据；复杂步骤需要后续
```
import-steps
```
、
```
add-ref
```
或
```
update --file
```
。
创建或更新后先
```
test-scenario get --with-case-detail
```
，确认步骤树和 HTTP 详情展开正常。
步骤间变量为空时，检查是否运行完整场景、步骤编号、响应路径、提取变量和环境选择。
不要把
```
test-case
```
的结构直接写成
```
test-scenario
```
步骤。

```
test-scenario create
```
only creates scenario metadata; complex steps require subsequent
```
import-steps
```
,
```
add-ref
```
, or
```
update --file
```
.
After creation or update, first execute
```
test-scenario get --with-case-detail
```
to confirm the step tree and HTTP details expand normally.
When variables between steps are empty, check if the full scenario is run, step number, response path, extracted variables, and environment selection.
Do not directly write
```
test-case
```
structure as
```
test-scenario
```
steps.

运行与报告排查

Execution and Report Troubleshooting

未指定
```
--environment
```
时，服务端可能使用项目默认环境；为了复现，建议显式指定。
本地报告看
```
--out-dir
```
和
```
--out-file
```
。
只有运行时带
```
--upload-report
```
，云端
```
test-report list/get/download
```
才能看到本次报告。
报告没有步骤详情时，先对比本地 JSON 和云端报告；本地也没有详情时，回查运行对象和资源结构。
有副作用的测试不要在生产环境默认执行。

When
```
--environment
```
is not specified, the server may use the project's default environment; for reproduction, it is recommended to specify it explicitly.
Check
```
--out-dir
```
and
```
--out-file
```
for local reports.
Only when
```
--upload-report
```
is included during execution can this report be viewed via cloud
```
test-report list/get/download
```
.
When the report lacks step details, first compare the local JSON and cloud report; if the local report also lacks details, review the execution object and resource structure.
Do not execute tests with side effects in the production environment by default.

常见分流

Common Diversion

现象	处理
新参数不识别	`apifox --version` 、 `which apifox` ，必要时 `apifox update --yes`
创建成功但页面没看到	检查 project、branch、模块、目录、分类、页面筛选
test-case 页面看不到	检查 `categoryId` 、endpoint、branch；用 `test-case list --endpoint` 回读
场景步骤不展示	`test-scenario get --with-case-detail` ，确认 create 后是否真正写入 steps
run-config 或运行前失败	确认 case/scenario/endpoint/environment/branch 都存在且一致
云端报告找不到	确认运行时是否带 `--upload-report`
agentHints 和 help 冲突	以当前 help 和实测为准，记录提示问题

Phenomenon	Handling
New parameter unrecognized	Execute `apifox --version` , `which apifox` , and `apifox update --yes` if necessary
Created successfully but not visible on page	Check project, branch, module, directory, category, and page filters
Test case not visible on page	Check `categoryId` , endpoint, branch; read back with `test-case list --endpoint`
Scenario steps not displayed	Execute `test-scenario get --with-case-detail` to confirm if steps are actually written after creation
run-config or pre-run failure	Confirm that case/scenario/endpoint/environment/branch all exist and are consistent
Cloud report not found	Confirm if `--upload-report` was included during execution
agentHints conflicts with help	Follow current help and actual tests, record the prompt issue