CLI Reference

The aisix binary runs the AISIX AI Gateway and provides the validate subcommand for working with declarative resources.yaml files. The subcommand runs without starting any listener, so it is safe to use on a workstation or in CI.

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

Command	Purpose
aisix --config <CONFIG>	Start the gateway with the given startup configuration file. See Configuration Files.
aisix validate --resources <FILE>	Check a resources file without starting the gateway.

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

Next Steps

• Run a gateway from a resources file with the Open-Source AISIX Gateway Quickstart.
• Confirm what a running gateway loaded with the Configuration Status endpoints.