apifox-cli-checkup

CLI Usage Check and Version Confirmation

Prerequisite: first read ../apifox-cli/SKILL.md. If the old general entry point conflicts with the rules of this skill, the current apifox <command> --help and this skill take precedence. Then read the corresponding business skill based on the resource type.

This skill is for public CLI usage troubleshooting and does not depend on internal interfaces or internal code. The goal is to confirm whether the command, project, branch, environment, resource ID, report location, and CLI version are consistent, and then return to the specific business skill to fix the resource structure. When troubleshooting, the Agent should prioritize forming a closed loop with the current help, schema validate, get readback, and agentHints, rather than only looking at the summary text.

When to Use

• The CLI returns success, but the Apifox page does not show the resource or shows it incompletely.
• After creation, list/get cannot find the resource.
• A test case, test scenario, or test suite run fails.
• The local report or cloud report cannot be found, or has no step details.
• agentHints, help, examples, or actual command behavior contradict each other.
• A user or tester reports "I don't have this parameter" or "the command doesn't recognize it", and you need to confirm the CLI version.

Do These 5 Things First

1. Record the original command, projectId, branch, resourceId, environmentId, file path, and whether it includes --api-base-url。
2. Run apifox --version, confirm the local CLI version; if a parameter does not exist, first check whether an update is needed.
3. Run the corresponding apifox <command> --help, and use the current public help as the standard; do not use parameters based on old documentation or memory.
4. Use the corresponding list/get to read back the resource and confirm whether it was written to the expected project, branch, module, directory, or category.
5. If it is a run or report issue, first distinguish between local reports and cloud reports: if --upload-report is not included, do not look for this run's result in the cloud report list.

Version Check

First check the version and command help:

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

If a new parameter required by the test instructions does not appear in help, prioritize updating the CLI:

apifox update

In a non-interactive environment or when confirming a direct update:

apifox update --yes

If the automatic update prompt interferes with troubleshooting, you can have the user set a disable for the daily check in the shell configuration, but this will not affect manual apifox update：

export APIFOX_CLI_DISABLE_UPDATE_CHECK=1

The version troubleshooting conclusion must clearly state: the current apifox --version, the command path (such as which apifox), the missing parameter name, and the recommended update method.

Help Conflicts with Prompts

• When public documentation, agentHints, historical examples, and actual behavior are inconsistent, the current apifox <command> --help and actual testing take precedence.
• Do not proactively recommend hidden aliases not exposed in help.
• success=false , rely on the real success fields and exit codes; do not trust the success semantics in the summary.
• If a command suggests a next step but the actual parameter does not exist, record it as a CLI prompt issue and use an alternative command exposed in help.

Resource Not Visible on the Page

Check first:

• Whether it was written to the correct project.
• Whether the correct --branch。
• Whether the resource is in the AI branch and the page is currently viewing the same branch.
• Whether it was written to the expected module or directory.
• Whether the test case uses a valid categoryId。
• When re-importing in Apifox native format, whether resources enter a new module due to module strategy.

Common read-back commands:

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 get/list can be seen, but the page cannot see it, first confirm whether the page filter conditions, branch, module, directory, and category are consistent; do not directly rebuild the resource.

Test case troubleshooting

• Before creation, you must use apifox test-case category --project <projectId> to obtain a valid categoryId。
• Current test-case category does not support --endpoint; to view test cases by endpoint, use test-case list --endpoint <endpointId>。
• test-case get Being able to see the structure only means the resource has been saved; it does not mean that requestBody, assertions, extracted variables, and scripts can definitely run.
• When a run 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 test-scenario get --with-case-detail, and confirm that the step tree and HTTP details expand normally.
• When variables between steps are empty, check whether the complete scenario is run, the step number, response path, extracted variables, and environment selection.
• Do not directly write the structure of test-case as test-scenario steps.

Run and report troubleshooting

• When --environment is not specified, the server may use the project default environment; to reproduce, it is recommended to specify it explicitly.
• For local reports, see --out-dir and --out-file。
• Only when --upload-reportis included at runtime, the cloud test-report list/get/download can see this report.
• When the report has no step details, first compare the local JSON and the cloud report; if there are no details locally either, trace back to the run object and resource structure.
• Do not run tests with side effects in the production environment by default.

Common triage

Symptom	Handling
New parameters not recognized	apifox --version、which apifox, if necessary apifox update --yes
Creation succeeds but the page does not show it	Check project, branch, module, directory, category, and page filters
The test-case page cannot see it	Check categoryId, endpoint, branch; use test-case list --endpoint to read back
Scenario steps are not displayed	test-scenario get --with-case-detail, confirm whether steps are actually written after create
run-config or failure before running	Confirm that case/scenario/endpoint/environment/branch all exist and are consistent
Cloud report cannot be found	Confirm whether it is included at runtime --upload-report
agentHints and help conflict	Base it on the current help and actual testing, and record prompt issues