Command Reference

API Declarative CLI (ADC) is a command-line tool for managing both APISIX and API7 Enterprise declaratively. It offers simplicity and clarity in defining the desired state of the gateway, allowing developers and administrators to focus on the result rather than the steps.

The declarative configurations serves as the single source of truth that developers can manage through their existing version control systems.

ADC has the following general syntax:

adc [command] [options]

with global options:

• -V, --version to check the version
• -h, --help to print the help menu of the command

Configuring ADC

ADC needs to be configured before it can be used to manage the gateway. You can configure ADC using environment variables or command-line flags.

Using Environment Variables

ADC exposes all configuration options as environment variables. For example, you can configure the backend type and address using the ADC_BACKEND and ADC_SERVER environment variables, respectively.

export ADC_BACKEND=api7ee
export ADC_SERVER=https://localhost:7443

A better way is to configure these options in a .env file:

.env

ADC_BACKEND=api7ee
ADC_SERVER=https://localhost:7443

Using Command-Line Flags

You can also configure ADC or overwrite the configuration in the environment variables using the command-line flags. For example, to configure/overwrite the backend type and address for the ping command:

adc ping --backend api7ee --server "https://localhost:7443"

Run adc help [command] to see the available configuration options for a command.

Commands

adc ping

Ping the configured backend to verify connectivity.

Option	Default Value	Description	Valid Values	Env Variable
--verbose <integer>	1	Overrides verbose logging levels.0 represents no log, 1 represents basic logs, and 2 represents debug logs.	0, 1 or 2
--backend <backend>	apisix	Backend type to connect.	apisix or api7ee	ADC_BACKEND
--server <string>	http://localhost:9180	Backend server address.		ADC_SERVER
--token <string>		API token to access the backend.		ADC_TOKEN
--gateway-group <string>	default	Gateway group to operate on.		ADC_GATEWAY_GROUP
--label-selector <selectors>		Resource labels to filter for.
--include-resource-type <string>		Filter for resource types, such that the resource search results should only contain the specified type.
--exclude-resource-type <string>		Filter for resource types, such that the resource search results should exclude the specified type.
--timeout <duration>	10s	Request timeout for the client to connect with the backend Admin API in duration, such as 30s, 10m, and 1h10m.
--ca-cert-file <string>		Path to CA certificate for verifying the backend Admin API.		ADC_CA_CERT_FILE
--tls-client-cert-file <string>		Path to mutual TLS client certificate for verifying the backend Admin API.		ADC_TLS_CLIENT_CERT_FILE
--tls-client-key-file <string>		Path to mutual TLS client key for verifying the backend Admin API.	ADC_TLS_CLIENT_KEY_FILE
--tls-skip-verify	false	Whether to verify the TLS certificate when connecting to the backend Admin API.	ADC_TLS_SKIP_VERIFY

Sample Usage

Check Connectivity with Configured Backend

adc ping

Check Connectivity with a Specified Backend

adc ping --backend api7ee --server https://localhost:7443

adc lint

Validate the provided configuration files locally.

Option	Default Value	Description	Valid Values	Env Variable
-f, --file <file-path>		Files to lint.

Sample Usage

Lint the Specified Configuration File

adc lint -f adc.yaml

Lint Multiple Configuration Files

adc lint -f service-a.yaml -f service-b.yaml

adc sync

Synchronize the local configuration to the connected backend.

Option	Default Value	Description	Valid Values	Env Variable
--verbose <integer>	1	Overrides verbose logging levels.0 represents no log, 1 represents basic logs, and 2 represents debug logs.	0, 1 or 2
--backend <backend>	apisix	Backend type to connect.	apisix or api7ee	ADC_BACKEND
--server <string>	http://localhost:9180	Backend server address.		ADC_SERVER
--token <string>		API token to access the backend.		ADC_TOKEN
--gateway-group <string>	default	Gateway group to operate on.		ADC_GATEWAY_GROUP
--label-selector <selectors>		Resource labels to filter for.
-f, --file <file-path>		Configuration files to synchronize.
--include-resource-type <string>		Filter for resource types, such that the resource search results should only contain the specified type.
--exclude-resource-type <string>		Filter for resource types, such that the resource search results should exclude the specified type.
--timeout <duration>	10s	Request timeout for the client to connect with the backend Admin API in duration, such as 30s, 10m, and 1h10m.
--ca-cert-file <string>		Path to CA certificate for verifying the backend Admin API.		ADC_CA_CERT_FILE
--tls-client-cert-file <string>		Path to mutual TLS client certificate for verifying the backend Admin API.		ADC_TLS_CLIENT_CERT_FILE
--tls-client-key-file <string>		Path to mutual TLS client key for verifying the backend Admin API.	ADC_TLS_CLIENT_KEY_FILE
--tls-skip-verify	false	Whether to verify the TLS certificate when connecting to the backend Admin API.	ADC_TLS_SKIP_VERIFY

Sample Usage

Synchronize Configuration from a Single File

adc sync -f adc.yaml

Synchronize Configuration from Multiple Files

adc sync -f service-a.yaml -f service-b.yaml

Synchronize Configuration to a Specific Gateway Group

adc sync -f adc.yaml --gateway-group production

Synchronize Configuration without Lint Check

adc sync -f adc.yaml --no-lint

Synchronize Configuration with Debug Logs

adc sync -f adc.yaml --verbose 2

Synchronize Configuration to a Specific Backend

adc sync -f service-a.yaml -f service-b.yaml --backend api7ee --server https://localhost:7443

Synchronize Only Specified Resource Types from the Configuration File

adc sync -f adc.yaml --include-resource-type global_rule --include-resource-type plugin_metadata

Synchronize Only the Resources with the Specified Labels

adc sync -f adc.yaml --label-selector app=catalog

adc dump

Save backend configuration to a local file.

Option	Default Value	Description	Valid Values	Env Variable
--verbose <integer>	1	Overrides verbose logging levels.0 represents no log, 1 represents basic logs, and 2 represents debug logs.	0, 1 or 2
--backend <backend>	apisix	Backend type to connect.	apisix or api7ee	ADC_BACKEND
--server <string>	http://localhost:9180	Backend server address.		ADC_SERVER
--token <string>		API token to access the backend.		ADC_TOKEN
--gateway-group <string>	default	Gateway group to operate on.		ADC_GATEWAY_GROUP
--label-selector <selectors>		Resource labels to filter for.
-o, --output <file-path>		Specify the file path where the backend data should be dumped.
--include-resource-type <string>		Filter for resource types, such that the resource search results should only contain the specified type.
--exclude-resource-type <string>		Filter for resource types, such that the resource search results should exclude the specified type.
--timeout <duration>	10s	Request timeout for the client to connect with the backend Admin API in duration, such as 30s, 10m, and 1h10m.
--ca-cert-file <string>		Path to CA certificate for verifying the backend Admin API.		ADC_CA_CERT_FILE
--tls-client-cert-file <string>		Path to mutual TLS client certificate for verifying the backend Admin API.		ADC_TLS_CLIENT_CERT_FILE
--tls-client-key-file <string>		Path to mutual TLS client key for verifying the backend Admin API.	ADC_TLS_CLIENT_KEY_FILE
--tls-skip-verify	false	Whether to verify the TLS certificate when connecting to the backend Admin API.	ADC_TLS_SKIP_VERIFY

Sample Usage

Save Backend Configuration to the Default adc.yaml file

adc dump

Save Backend Configuration to a Specified File

adc dump -o service-configuration.yaml

Save Only Specified Resource Types from the Backend

adc dump --include-resource-type global_rule --include-resource-type plugin_metadata

Save Only the Resources with the Specified Labels

adc dump --label-selector app=catalog

Save Configuration from a Specified Backend

adc dump -o api7ee-dump.yaml --backend api7ee --server https://localhost:7443

adc diff

Show differences in the configuration between the local file and the backend.

Option	Default Value	Description	Valid Values	Env Variable
--verbose <integer>	1	Overrides verbose logging levels.0 represents no log, 1 represents basic logs, and 2 represents debug logs.	0, 1 or 2
--backend <backend>	apisix	Backend type to connect.	apisix or api7ee	ADC_BACKEND
--server <string>	http://localhost:9180	Backend server address.		ADC_SERVER
--token <string>		API token to access the backend.		ADC_TOKEN
--gateway-group <string>	default	Gateway group to operate on.		ADC_GATEWAY_GROUP
--label-selector <selectors>		Resource labels to filter for.
-f, --file <file-path>		Configuration files to compare.
--include-resource-type <string>		Filter for resource types, such that the resource search results should only contain the specified type.
--exclude-resource-type <string>		Filter for resource types, such that the resource search results should exclude the specified type.
--timeout <duration>	10s	Request timeout for the client to connect with the backend Admin API in duration, such as 30s, 10m, and 1h10m.
--ca-cert-file <string>		Path to CA certificate for verifying the backend Admin API.		ADC_CA_CERT_FILE
--tls-client-cert-file <string>		Path to mutual TLS client certificate for verifying the backend Admin API.		ADC_TLS_CLIENT_CERT_FILE
--tls-client-key-file <string>		Path to mutual TLS client key for verifying the backend Admin API.	ADC_TLS_CLIENT_KEY_FILE
--tls-skip-verify	false	Whether to verify the TLS certificate when connecting to the backend Admin API.	ADC_TLS_SKIP_VERIFY

Sample Usage

Compare Configuration in a Specified File with the Backend Configuration

adc diff -f adc.yaml

Compare Configuration in Multiple Files with the Backend Configuration

adc diff -f service-a.yaml -f service-b.yaml

Compare Configuration in the Specified Files with the Specified Backend

adc diff -f service-a.yaml -f service-b.yaml --backend api7ee --server https://localhost:7443

adc convert

Convert API specification to ADC configuration.

Option	Default Value	Description	Valid Values	Env Variable
openapi		Convert an OpenAPI specification to ADC configuration.

Sample Usage

Convert OpenAPI Specification in YAML Format to ADC Configuration and Save to the Default adc.yaml File

adc convert openapi -f openapi.yaml

Convert OpenAPI Specification in JSON Format to ADC Configuration and Save to a Specified File

adc convert openapi -f openapi.json -o converted-adc.yaml

See OpenAPI Converter Reference for more documentation.

adc help

Print the general help menu or the help menu for the specified command.

Sample Usage

adc help [command]