Configuration of kongctl

kongctl provides a flexible system for configuring CLI behavior, so you can customize settings for different machines, Konnect organizations, environments, and automation pipelines.

Note: The term configuration in this document refers to changing the behavior of the CLI itself, not to be confused with declarative configuration, which is used to manage the state of Konnect resources. For declarative configuration, see the declarative configuration guide.

kongctl supports named collections of configuration values, which are called profiles. You can use profiles to separate configurations for any purpose you need. Common usage includes different organizations, regions, or machines.

Using profiles is optional. If no profile is specified, a built-in profile named default is applied.

Sample configuration snippet:

my-profile:     # profile name
  output: json  # configuration value
  konnect:       
    region: us  # configuration names can be nested

Each kongctl invocation uses a single profile to determine which configuration values to apply. You can specify the profile in different ways:

# No profile specified, the 'default' profile is implied
kongctl get apis

# Specify profile with flag
kongctl get apis --profile production

# Specify profile with environment variable
KONGCTL_PROFILE=production kongctl get apis

# Export a profile via environment variable
export KONGCTL_PROFILE=production
# Uses the production profile 
kongctl get apis
# Also uses the production profile 
kongctl apply -f config.yaml

All kongctl configuration values can be loaded via flags, environment variables, or the configuration file. This allows you to set defaults in files while overriding them as needed for specific commands or environments.

All configuration values are specified via a path. The path to a particular configuration value is provided in the usage text of the command. For example, the Konnect region configuration value is shown in the help text as:

--region string     Konnect region identifier (for example "eu")... 
                          - Config path: [ konnect.region ]

This shows that you can specify a region with the --region flag, but you can also set it in the configuration file or via environment variables based on the config path.

In the configuration file, this value would be set under the profile name with the following YAML syntax:

default:
  konnect:
    region: eu

Most resource commands support text, json, and yaml output. Text output is optimized for reading in a terminal and can omit fields or truncate long values. Use JSON or YAML when automation needs the complete response.

Configure the default output format for a profile:

default:
  output: json

Text output has two profile settings:

For example:

default:
  output: text
  text:
    layout: auto
    id-format: full

compact is the default layout. auto adds fields when the output is a wide enough terminal and otherwise uses the compact layout. wide selects every safe text field. The default ID format is compact.

On commands that support it, repeat --columns HEADER=.field to replace the built-in text columns:

kongctl get apis \
  --columns NAME=.name \
  --columns UPDATED=.updated_at

--columns works only with text output and can’t be combined with --jq. Use --jq with JSON or YAML output when you need to transform structured output.

When values are loaded via environment variables, the variable names must start with the KONGCTL_ prefix, then the desired profile, and finally the config path in uppercase with underscores instead of dots.

For example, to set the same region value for the default profile, set the following environment variable:

KONGCTL_DEFAULT_KONNECT_REGION=eu

Note: The KONGCTL_ prefix configures the kongctl CLI. To inject an environment variable into a declarative resource, use the !env YAML tag.

By default, kongctl reads configurations from a file located at $XDG_CONFIG_HOME/kongctl/config.yaml and falls back to ~/.config/kongctl/config.yaml if XDG_CONFIG_HOME is not set.

You can specify a different configuration file via the --config-file flag:

--config-file string   Path to the configuration file to load.
                             - Default: [ $XDG_CONFIG_HOME/kongctl/config.yaml ]

Precedence

kongctl configuration values are loaded in the following precedence (highest to lowest):

1. Command-line flags: Explicit flags like --pat, --region, --output
2. Environment variables: KONGCTL_<PROFILE>_<CONFIG_PATH> variables
3. Configuration file: Values in config.yaml
4. Default values: Built-in defaults