CLI Reference

The aisix binary runs the AISIX gateway and provides commands for working with open-source AISIX gateway configuration. Use validate to check a declarative resources.yaml file and export to convert resources in an existing etcd store into that format. Both commands run without starting gateway listeners.

Usage: aisix --config <CONFIG>
       aisix <COMMAND>

Command	Purpose
aisix --config <CONFIG>	Start the gateway with the given startup configuration file. See the Startup Configuration Reference.
aisix validate --resources <FILE>	Check a resources file without starting the gateway.
aisix export --etcd <ENDPOINT> [-o <FILE>]	Export resources from an open-source AISIX gateway's etcd store as a loadable resources file.

When running the official container image, invoke the binary directly:

docker run --rm --entrypoint /usr/local/bin/aisix ghcr.io/api7/aisix:latest --help

Validate a Resources File

aisix validate runs the identical pipeline the gateway uses to load a resources file — read, ${VAR} interpolation, name-reference resolution, canonical schema validation, and cross-reference checks — without starting any listener. Use it as a pre-check before a boot or a reload, or as a CI gate on configuration changes.

aisix validate --resources resources.yaml

Option	Required	Description
--resources <FILE>	Yes	Path to the resources file to validate.

${VAR} references in the file resolve against the environment of the validate process itself. Run the command with the same variables the gateway will receive, or validation fails on the unresolved references.

Exit Codes

Exit code	Meaning
0	The file loads. A summary is printed to standard output.
Non-zero	The file does not load. The full aggregated error report is printed to standard error.

On success:

OK: resources.yaml loaded 3 resource(s)

On failure, every problem across the whole file is reported together, with the resource kind, entry, and field:

resources file resources.yaml: 3 error(s):
  - provider_keys[0]: field `api_key`: environment variable `OPENAI_API_KEY` is unset or empty
  - models[0] ("gpt-4o-mini"): `provider_key` references unknown provider key "openai-main" (no provider_keys are defined in this file)
  - api_keys[0] ("quickstart-caller"): `key_env` environment variable `CALLER_API_KEY` is unset or empty

Validate with the Container Image

Without a local binary, run the same check through Docker. Mount the file and pass the environment variables it references:

docker run --rm \
  -v "$(pwd)/resources.yaml:/etc/aisix/resources.yaml:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  --entrypoint /usr/local/bin/aisix \
  ghcr.io/api7/aisix:latest \
  validate --resources /etc/aisix/resources.yaml

Export Resources from etcd

aisix export reads resources from an open-source AISIX gateway's etcd prefix and writes them to a declarative resources file. Use it to move an etcd-backed gateway to a resources file. This includes gateways whose resources were created through the gateway Admin API in earlier releases. The command can also create a reviewable backup of resources the gateway can load.

aisix export \
  --etcd "http://127.0.0.1:2379" \
  --output resources.yaml

Option	Required	Description
--etcd <ENDPOINT>	Yes	etcd endpoint to read. Repeat the option or provide a comma-separated list for multiple endpoints.
--prefix <PREFIX>	No	Key prefix containing the resources. Defaults to /aisix, the gateway's default etcd.prefix.
-o, --output <FILE>	No	Write the YAML document to a file instead of standard output. On Unix, AISIX creates or resets the file with mode 0600.
--reveal-secrets	No	Write stored credentials inline instead of replacing them with environment-variable placeholders. The resulting output contains live secrets.

The export follows the same etcd decoding path as the running gateway. It converts resource references back to display names and omits generated IDs so the resulting document follows the resources-file format.

By default, stored credentials are replaced with ${VAR} placeholders. AISIX prints the placeholder names and their source fields to standard error. Set those variables in the gateway environment before loading the exported file.

caution

Use --reveal-secrets only for a controlled migration where plaintext credentials must remain in the file. Do not commit, publish, or copy that output to an unsecured location.

The command reports etcd entries that it could not decode and warnings about resource relationships. It still writes the output for inspection. It exits non-zero when naming collisions or dangling references prevent the file from loading. Validate the completed file before switching the gateway to it:

aisix validate --resources resources.yaml