CLI Usage Check and Version Verification

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 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.

First 5 Actions

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

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.

Conflict Between Help and Hints

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

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

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
```
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

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

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

apifox-cli-checkup

NPX Install

Tags

SKILL.md Content (Chinese)

CLI Usage Check and Version Verification

When to Use

First 5 Actions

Version Check

Conflict Between Help and Hints

Resource Not Visible on Page

Test Case Troubleshooting

Test Scenario Troubleshooting

Execution and Report Troubleshooting

Common Diversion