Apifox CLI

apifox-cli is now a Go command line tool plus an AI Skill for writing Apifox/OpenAPI documentation. The CLI replaces the old tool-call workflow: agents and scripts should call apifox-cli commands directly.

The main use case is not importing an existing OpenAPI file. The expected workflow is:

1. Read routes, handlers, DTOs, validators, and product requirements from the target project.
2. Write structured hidden JSON files such as .apifox-docs.json, .apifox-endpoint.json, .apifox-crud.json, or .apifox-schema.json.
3. Validate locally.
4. Run --dry-run.
5. Apply the generated documentation to Apifox through the CLI.

For Go projects, do not use Swagger marker comments as the primary API documentation strategy. Keep Go code focused on implementation and let AI author structured OpenAPI/Apifox specs through this CLI.

Install

Homebrew:

brew tap iwen-conf/tap
brew trust iwen-conf/tap
brew install --cask apifox-cli
apifox-cli --version

From source:

go build -o ./bin/apifox-cli ./cmd/apifox-cli
./bin/apifox-cli --help

Or install from the checkout:

go install ./cmd/apifox-cli
apifox-cli --help

Configure

Set credentials through environment variables, or pass them before the subcommand with --token and --project-id.

export APIFOX_TOKEN="your-token"
export APIFOX_PROJECT_ID="your-project-id"

apifox-cli config check

Use --base-url only when your Apifox deployment is not https://api.apifox.com.

CLI Commands

Use the canonical command surface in new scripts: api create|update|upsert, schema create|update, apply-docs, and generate-crud. The older create-endpoint, update-endpoint, and upsert-endpoint commands are legacy aliases for compatibility.

Every command and subcommand supports --help without requiring credentials, files, or network access. JSON-file inputs accept --file - for stdin. Validation commands support --json with output shaped as {"valid": bool, "errors": [...]} and exit with code 1 when invalid. Discovery, audit, and write commands return structured --json output for scripts.

Direct endpoint/schema/folder deletion and folder creation are not currently supported as mutating operations; those commands explain the limitation. Prefer tags for folder-like organization.

Project and discovery:

apifox-cli config check
apifox-cli versions
apifox-cli api list --limit 20
apifox-cli api get --method GET --path /orders
apifox-cli schema list --limit 20
apifox-cli schema get Order
apifox-cli tag list
apifox-cli folder list

Endpoint documentation:

apifox-cli endpoint-template --method POST -o .apifox-endpoint.json
apifox-cli validate-endpoint --file .apifox-endpoint.json
apifox-cli api upsert --file .apifox-endpoint.json --dry-run
apifox-cli api upsert --file .apifox-endpoint.json

Batch AI documentation:

apifox-cli docs-template -o .apifox-docs.json
apifox-cli validate-docs --file .apifox-docs.json
apifox-cli apply-docs --file .apifox-docs.json --dry-run
apifox-cli apply-docs --file .apifox-docs.json

For broad writes, apply batches with --offset and --limit:

apifox-cli apply-docs --file .apifox-docs.json --batch-size 15 --dry-run
apifox-cli apply-docs --file .apifox-docs.json --offset 0 --limit 15
apifox-cli apply-docs --file .apifox-docs.json --offset 15 --limit 15

CRUD and schema documentation:

apifox-cli crud-template -o .apifox-crud.json
apifox-cli validate-crud --file .apifox-crud.json
apifox-cli generate-crud --file .apifox-crud.json --dry-run
apifox-cli generate-crud --file .apifox-crud.json

apifox-cli schema template -o .apifox-schema.json
apifox-cli schema create --file .apifox-schema.json --dry-run
apifox-cli schema create --file .apifox-schema.json

Maintenance and audits:

apifox-cli tag apis --tag 订单管理
apifox-cli tag add --method GET --path /orders --tag 订单管理 --tag 核心接口
apifox-cli audit responses --method POST --path /orders
apifox-cli audit all-responses --tag 订单管理
apifox-cli audit path-naming --style kebab-case
apifox-cli audit consistency

Raw Apifox /v1 fallback for official endpoints that are not wrapped yet:

apifox-cli request GET /versions --json
apifox-cli request POST /projects/123/export-openapi --data-file .apifox-export-payload.json

AI Skill

The repository includes a Codex Skill at skills/apifox-cli. Use it when an AI agent needs to write or maintain Apifox/OpenAPI docs from source code.

The Skill instructs the agent to:

• Read application code and requirements first.
• Write hidden JSON specs instead of editing Swagger comments in Go code.
• Run validate-* locally.
• Run --dry-run before writing to Apifox.
• Use CLI commands such as api upsert, schema create, generate-crud, and apply-docs.

JSON Spec Rules

Endpoint specs must include a business title, path, method, description, structured request/response schemas, and real examples. Every schema field and parameter must include description.

Example .apifox-endpoint.json:

{
  "title": "创建订单",
  "path": "/orders",
  "method": "POST",
  "description": "创建订单，需要用户已登录",
  "tags": ["订单管理"],
  "request_body_schema": {
    "type": "object",
    "properties": {
      "item_id": {"type": "integer", "description": "商品ID"},
      "quantity": {"type": "integer", "description": "购买数量"}
    },
    "required": ["item_id", "quantity"]
  },
  "request_body_example": {"item_id": 1001, "quantity": 2},
  "response_schema": {
    "type": "object",
    "properties": {
      "order_id": {"type": "integer", "description": "订单ID"},
      "status": {"type": "string", "description": "订单状态"}
    },
    "required": ["order_id", "status"]
  },
  "response_example": {"order_id": 90001, "status": "pending"}
}

Import And Export

OpenAPI import/export remains available for migration, backup, and compatibility work. It is not the primary AI authoring path.

apifox-cli export-openapi --format JSON --oas-version 3.1 -o .apifox-openapi.json
apifox-cli export-openapi --scope tags --tag 订单管理 --format YAML -o .apifox-orders.yaml
apifox-cli import-openapi --file .apifox-openapi.json --endpoint-overwrite-behavior AUTO_MERGE
apifox-cli import-openapi --url https://example.com/openapi.yaml --prepend-base-path
apifox-cli import-postman --file .postman-collection.json

Preview mutating import/export requests before calling Apifox:

apifox-cli export-openapi --scope tags --tag 订单管理 --dry-run
apifox-cli import-openapi --file .apifox-openapi.json --print-payload

Develop

go test ./...
go build -o /tmp/apifox-cli ./cmd/apifox-cli
/tmp/apifox-cli --help
/tmp/apifox-cli docs-template | /tmp/apifox-cli validate-docs --file -

Release uses GoReleaser and the Homebrew cask in iwen-conf/homebrew-tap.