apifox-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apifox CLI

用 Apifox CLI 完成用户请求；不要凭记忆拼 payload，优先让 CLI 的

--help

、

cli-schema

、

cli-schema validate

、

agentHints.nextSteps

驱动下一步。

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

首次处理 Apifox CLI 任务时，先轻量确认 CLI 可用：
```
apifox --version
```
、
```
apifox --help
```
。

如果

apifox

不存在或无法输出版本，先安装 CLI：

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

。

安装后执行
```
apifox login --with-token <TOKEN>
```
登录。API 访问令牌可在 Apifox 客户端或网页端「用户头像 → 账号设置 → API 访问令牌」创建。
不要每次默认升级；只有命令返回版本过低/unknown command/参数缺失疑似旧版导致，或用户任务依赖新能力时，才建议升级。

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

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

常用全局参数：

text

--project <projectId>     项目 ID
--branch <branchName>     分支名；纯数字值兼容旧 branchId
--access-token <token>    覆盖当前登录 token
--api-base-url <url>      私有部署地址

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

未登录时让用户提供 API 访问令牌，执行：
```
apifox login --with-token <TOKEN>
```
。
Apifox CLI 的鉴权凭证存在
```
~/.apifox/config.toml
```
；不要把 token 打印到日志、提交到仓库或写进普通聊天摘要。
如果用户未指定项目，先查看当前工作区是否存在
```
.apifox/settings.json
```
；如其中有常用默认
```
projectId
```
，优先使用该项目。
项目 ID 可推荐用户从「项目设置 - 基本设置 - 项目 ID」获取；或先执行
```
apifox project list
```
，给用户确认需执行命令的目标项目。
写入任何本地配置文件前先询问用户。

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

强制：执行

create

或

update

命令前必须先获取完整的资源定义和数据格式，并在正式执行前通过

cli-schema validate

校验写入准确，具体流程：

查对应资源执行命令的 JSON schema：
```
apifox cli-schema get <schemaKey>
```
生成资源的 JSON 数据文件。

校验：

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

只有
```
validate
```
无误后，才执行真实
```
create
```
或
```
update
```
命令。

命令输出结果后，优先读取 JSON 输出里的

agentHints.nextSteps

继续执行或恢复。

Mandatory: Before executing

create

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 事实优先

CLI Fact Priority

具体命令、参数、schema key 以当前 CLI 输出为准：
```
apifox <command> --help
```
、
```
apifox cli-schema list
```
、
```
agentHints.nextSteps
```
。
如本 skill 与当前 CLI 输出不一致，以当前 CLI 输出执行，并同步修正本 skill 的事实性描述。

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 写入权限声明

CLI Writing Permission Declaration

执行写入被 AI（CLI 来源）权限限制时，若用户未声明，不要替用户选择，优先询问写入方式：开启目标分支的直接编辑权限，或在 AI 分支上编辑目标分支数据。
如用户需直接编辑主分支、迭代分支或通用分支数据，请用户在 Apifox 客户端 2.8.32+ 版本在「项目设置 - 功能设置 - AI 功能设置 - 外部 AI 编辑权限」开启直接编辑权限的开关。
如用户选择 AI 分支，流程是： step1：创建 AI 分支并指定来源分支； step2：按实际需要导入（pick-to）来源分支资源； step3：按用户需求编辑 AI 分支； step4：完成后，提醒用户确认是否发起合并请求或合并。
从 CLI 直接执行合并/合并请求时，要求来源分支和目标分支的直接编辑权限开关均已开启；否则请提醒用户先打开对应分支类型的权限开关，或直接在客户端手动触发合并。

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 分支说明

AI Branch Description

AI 分支是给 AI/自动化修改项目资源的隔离分支，避免直接污染源分支。
AI 分支若在 24 小时内与来源分支无差异，将自动归档。
AI 分支初始为空，不会自动 clone 源分支资源；编辑/删除来源分支已有资源前，先导入到 AI 分支。
AI 分支中新建资源无需先导入。
AI 分支修改不会自动写回源分支；完成后必须让用户确认是否立刻合并或发起合并请求。
目标主分支受保护时（isProtected），优先走
```
merge-request
```
，不要直接
```
merge
```
。

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

登录 token、本地配置写入、私有部署地址。
创建/切换 AI 分支、导入源分支资源到 AI 分支。
删除、归档、覆盖导入、批量更新等破坏性操作。
将 AI 分支改动 merge / merge-request 回源分支。
是否升级 CLI。

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

现象	处理
未登录	`apifox login --with-token <TOKEN>`
不知道项目	`apifox project list`
不知道命令参数	`apifox <command> --help`
参数或 schema 错误	先跑 `cli-schema get` / `cli-schema validate`
AI 写入受限	解释 AI 分支/权限开关，让用户选择
私有部署	加 `--api-base-url https://your-server`

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`