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:
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]