apifox-cli

Original：🇨🇳 Chinese

Translated

Manage Apifox project resources via Apifox CLI. Trigger scenarios: Run API automated testing/test suites, query/create/update/delete project resources such as APIs, environments, Schema, Mock, branches, import and export API documents, view test reports, manage CI/CD configurations like Runner, scheduled tasks, notifications. CLI output is structured JSON, often containing agentHints.nextSteps; all commands support --help.

3installs

Sourceapifox/apifox-cli-skills

Added on2026-08-11

NPX Install

npx skill4agent add apifox/apifox-cli-skills apifox-cli

SKILL.md Content (Chinese)

View Translation Comparison →

Apifox CLI

Complete user requests using Apifox CLI; do not construct payloads from memory. Prioritize driving next steps with the CLI's

--help

,

cli-schema

,

cli-schema validate

, and

agentHints.nextSteps

.

New Session Check

When handling an Apifox CLI task for the first time, first confirm the CLI is available with lightweight checks:
```
apifox --version
```
,
```
apifox --help
```
.

If

apifox

does not exist or cannot output the version, install the CLI first:

npm i -g apifox-cli@latest --registry=https://registry.npmmirror.com/

.

After installation, log in with
```
apifox login --with-token <TOKEN>
```
. The API access token can be created in the Apifox client or web portal under "User Avatar → Account Settings → API Access Token".
Do not upgrade by default every time; only suggest upgrading if the command returns errors like outdated version/unknown command/missing parameters suspected to be caused by an old version, or if the user's task relies on new features.

Basic Usage

bash

apifox --help
apifox <command> --help
apifox <command> <subcommand> --help

Common global parameters:

text

--project <projectId>     Project ID
--branch <branchName>     Branch name; pure numeric values are compatible with old branchId
--access-token <token>    Override current login token
--api-base-url <url>      Private deployment address

Login and Projects

When not logged in, ask the user for an API access token and execute:
```
apifox login --with-token <TOKEN>
```
.
Apifox CLI authentication credentials are stored in
```
~/.apifox/config.toml
```
; do not print the token to logs, commit it to repositories, or write it into ordinary chat summaries.
If the user does not specify a project, first check if
```
.apifox/settings.json
```
exists in the current workspace; if it contains a commonly used default
```
projectId
```
, prioritize using that project.
Recommend users obtain the project ID from "Project Settings - Basic Settings - Project ID"; alternatively, first execute
```
apifox project list
```
and ask the user to confirm the target project for the command to be executed.
Ask the user before writing to any local configuration files.

Standard Writing Process

Mandatory: Before executing

create

or

update

commands, you must first obtain the complete resource definition and data format, and validate the writing accuracy via

cli-schema validate

before formal execution. The specific process is:

Retrieve the JSON schema for the corresponding resource execution command:
```
apifox cli-schema get <schemaKey>
```
Generate a JSON data file for the resource.

Validate:

apifox cli-schema validate <schemaKey> --file <path>

Only execute the actual
```
create
```
or
```
update
```
command after
```
validate
```
passes without errors.

After the command outputs results, prioritize reading

agentHints.nextSteps

in the JSON output to continue execution or recover.

CLI Fact Priority

Specific commands, parameters, and schema keys are subject to the current CLI output:
```
apifox <command> --help
```
,
```
apifox cli-schema list
```
,
```
agentHints.nextSteps
```
.
If this skill conflicts with the current CLI output, execute according to the current CLI output and synchronously correct the factual descriptions in this skill.

CLI Writing Permission Declaration

When writing is restricted by AI (CLI source) permissions and the user has not specified, do not make choices for the user. Prioritize asking the user about the writing method: enable direct editing permissions for the target branch, or edit target branch data on an AI branch.
If the user needs to directly edit data on the main branch, iteration branch, or general branch, ask the user to enable the direct editing permission switch in Apifox client version 2.8.32+ under "Project Settings - Feature Settings - AI Feature Settings - External AI Editing Permissions".
If the user selects an AI branch, the process is: step1: Create an AI branch and specify the source branch; step2: Import (pick-to) resources from the source branch as needed; step3: Edit the AI branch according to the user's requirements; step4: After completion, remind the user to confirm whether to initiate a merge request or merge.
When executing merge/merge requests directly from the CLI, require that the direct editing permission switches for both the source branch and target branch are enabled; otherwise, remind the user to enable the permission switch for the corresponding branch type first, or manually trigger the merge in the client.

AI Branch Description

AI branches are isolated branches for AI/automated modifications to project resources, avoiding direct contamination of the source branch.
If an AI branch has no differences from the source branch within 24 hours, it will be automatically archived.
AI branches are initially empty and do not automatically clone source branch resources; before editing/deleting existing resources from the source branch, import them to the AI branch first.
There is no need to import first when creating new resources in an AI branch.
Modifications to AI branches will not be automatically written back to the source branch; after completion, the user must confirm whether to merge immediately or initiate a merge request.
When the target main branch is protected (isProtected), prioritize using
```
merge-request
```
instead of direct
```
merge
```
.

Must Ask the User

Login token, local configuration writing, private deployment address.
Creating/switching AI branches, importing source branch resources to AI branches.
Destructive operations such as deletion, archiving, overwriting import, batch update.
Merging/merging-request changes from AI branches back to the source branch.
Whether to upgrade the CLI.

Fault Recovery

Symptom	Troubleshooting
Not logged in	`apifox login --with-token <TOKEN>`
Unknown project	`apifox project list`
Unknown command parameters	`apifox <command> --help`
Parameter or schema error	Run `cli-schema get` / `cli-schema validate` first
AI writing restricted	Explain AI branches/permission switches and let the user choose
Private deployment	Add `--api-base-url https://your-server`