The Kong Konnect CLI

kongctl is a Tech Preview project. This software is provided by Kong, Inc. without warranty and is not recommended for production use. The CLI is under active development - interfaces, commands, and behaviors are subject to change without notice. Use at your own risk for evaluation and testing purposes only.

By using this software, you acknowledge that:

• It may contain bugs and incomplete features
• It should not be used for critical systems or production workloads
• Data loss or service disruption may occur
• No support commitments or SLAs apply

• What is kongctl?
• Installation
  • macOS
  • Linux
  • Verify
• Getting Started
  • 1. Create a Kong Konnect Account
  • 2. Authenticate with Konnect
  • 3. Test the Authentication
  • 4. Switch Region
  • 5. Next Steps
• Documentation Listing
• Configuration and Profiles
  • Color Themes
  • Authentication Options
• Command Structure
• Support

kongctl is a command-line tool for Kong Konnect that enables you to:

• Manage Konnect resources programmatically
• Define your Konnect API infrastructure as code using declarative configuration
• Integrate Konnect into your CI/CD pipelines
• Automate API lifecycle management

Note: Future releases may include support for Kong Gateway on-premise deployments.

Install using Homebrew (distributed as a cask):

brew install --cask kong/kongctl/kongctl

If you previously installed the old formula, remove it first with brew uninstall kongctl.

Download from the release page:

# Example: Install v0.0.12 for x86-64
curl -sL https://github.com/Kong/kongctl/releases/download/v0.0.12/kongctl_linux_amd64.zip -o kongctl_linux_amd64.zip
unzip kongctl_linux_amd64.zip -d /tmp
sudo cp /tmp/kongctl /usr/local/bin/

kongctl version --full

If you don't have a Kong Konnect account, sign up for free.

Use the kongctl login command to authenticate with you Kong Konnect account:

kongctl login

Follow the instructions given in the terminal to complete the login process.

You can verify that kongctl is authenticated and can access information on your Konnect account by running:

kongctl get me 

By default kongctl uses the us region for Konnect API requests. Until a feature is developed to easily support region switching, you need to set the base-url configuration to route requests to a different region.

You can set the base-url using the --base-url flag or by configuring it in your profile. The base-url format is https://<region>.api.konghq.com, where <region> is the region code (for example, eu for Europe). The documentation provides a list of available regions.

Here is an example configuration snippet to set the default profile to use the eu region:

default:
    ...
    konnect:
      base-url: https://eu.api.konghq.com
    ...

→ Read the Declarative Configuration Guide - Learn how to use declarative configuration to manage your APIs in Konnect

• Declarative Configuration Guide - Complete guide covering quick start, concepts, YAML tags, CI/CD integration, and best practices
• Troubleshooting Guide - Common issues and solutions
• Examples - Sample configurations and use cases
• E2E Test Harness - How to run end-to-end tests locally and in CI

kongctl configuration data is read from $XDG_CONFIG_HOME/kongctl and falls back to $HOME/.config/kongctl. The standard configuration file (YAML format) is located in this location and is named config.yaml. At the root level you specify profiles where a profile is a named collection of configuration values. By default there is a default profile, but you can create additional profiles for different environments or configurations.

Some flags and options can be changed by providing a value in the configuration file, effectively allowing you to override the default behavior of command options. Flags that support this will be documented in the command help text with a "Config path" note that looks like this:

-o, --output string        Configures the format of data written to STDOUT.
                             - Config path: [ output ]
                             - Allowed    : [ json|yaml|text ] (default "text")

The above help text shows a YAML key path for the --output flag which controls the format of output text from the CLI. The config path is the location in the configuration file where a flag value can be defaulted. In this case it specifies that output formats can be set in the configuration file under an output key.

The basic example of a configuration file follows:

default:
  output: text
second-profile:
  output: json

Specifying a profile can be done using the --profile flag or by setting or exporting the KONGCTL_PROFILE environment variable.

Configuration values can also be specified using environment variables. kongctl looks for environment variables which follow the pattern KONGCTL_<PROFILE>_<PATH>, where <PROFILE> is the profile name in uppercase and <PATH> is the configuration path in uppercase. For example, to set the output format for the default profile, you can use:

KONGCTL_DEFAULT_OUTPUT=yaml kongctl get apis 

kongctl makes requests to the Konnect API using API tokens. There are two primary methods for authentication.

1. Device Flow (Recommended):

   Execute the following command to authorize kongctl with your Kong Konnect account:

   kongctl login

   This command will generate a web link you can use to open a browser window and authenticate with your Kong Konnect account. After logging in and authorizing the CLI using the provided code, kongctl will store token and refresh token data in a file at $XDG_CONFIG_HOME/kongctl/.<profile>-konnect-token.json

2. Personal Access Token flag:

   You can also pass an API token directly using the --pat flag. This is useful for automation pipelines where you want to avoid interactive login or provide various tokens for different operations.

   kongctl get apis --pat <token>

   You can also set an environment variable for the token following the same pattern as configuration values:

   KONGCTL_DEFAULT_KONNECT_PAT=<token> kongctl get apis
   

Interactive experiences, such as kongctl kai or kongctl view, share a configurable color theme. Use the --color-theme flag (or set the color-theme key in your configuration file) to select a palette. The default kong theme mirrors the existing brand styling, and you can switch to any bubbletint theme by ID, for example:

default:
  color-theme: tokyo_night

Commands generally follow a verb->product->resource->args pattern with konnect as the default product.

kongctl <verb> <product> <resource-type> [resource-name] [flags]

Examples:

• kongctl get apis - List all APIs in Konnect (konnect product is implicit)
• kongctl get konnect apis - List all APIs in Konnect (using full product name)
• kongctl get api users-api - Get specific API details
• kongctl delete api my-api - Delete an API from Konnect

• Issues: GitHub Issues
• Documentation: Kong Docs
• Community: Kong Nation

Remember: This is tech preview software. Please report bugs and provide feedback through GitHub Issues or the Kong Nation community.