kongctl
Kong's swiss-army knife command line tool for managing and interacting with Kong KonnectWhat is kongctl?
kongctl is a command line tool that enables you to manage Konnect resources programmatically. The tool provides both declarative and imperative style resource management capabilities along with other developer friendly features.
The declarative configuration feature allows you to define API Platform infrastructure as code using a YAML based syntax and a state free reconciliation system. The tool supports a growing list of Konnect resource types including Dev Portals, control planes, APIs, and more.
kongctl is one of multiple tools you can use to manage Konnect and Kong Gateway. To learn about other tools, see the tools page.
When should I use kongctl?
You should use kongctl if one or more of the following is true:
- You are a developer or platform engineer looking to manage your Konnect resources
- You’re building CI/CD pipelines for full API Platform lifecycle automation
- You want to manage Konnect resources with declarative, file-based configuration and automation
- You want to avoid Terraform for declarative management due to syntax or state management concerns
- You want command-line friendly access to Konnect for ad-hoc resource queries
What can kongctl do?
kongctl is a multi-purpose tool providing Konnect resource management capabilities as well as other developer focused features.
Declarative Configuration: Define your infrastructure in YAML files and use plan-based workflows to preview and apply changes. The declarative engine is stateless and calculates differences by querying live Konnect resources.
Resource Viewing: Get or list resources directly from the command line with human-friendly or machine-readable output formats as well as a terminal-based user interface with keyboard navigation.
Flexible Authorization: kongctl communicates with Konnect via its APIs and supports authentication through browser-based device flow or personal access tokens.
Other tools
- decK: Manage Kong Gateway configuration with declarative, file-based automation
- Terraform: Manage infrastructure as code and automated deployments
- KIC: Manage ingress traffic and routing rules for Kubernetes services
- APIs: Manage Konnect programatically via direct API calls
- Kong Gateway Admin API: Manage on-prem Kong Gateway entities via an API
Example commands
View all kongctl commands and options
kongctl --help
Authenticate to Konnect with browser-based device flow
kongctl login
List all APIs in your Konnect organization
kongctl get apis
Get details for a specific API with JSON output
kongctl get api users-api --output json
Call Konnect APIs directly using current authentication
kongctl api /v3/portals
Launch interactive terminal UI to explore resources
kongctl view
Generate a plan from input configuration without invoking changes
kongctl plan -f my-portals.yaml --output-file plan.json
Apply (create and update only) changes from input configuration
kongctl apply -f my-portals.yaml -f my-apis.yaml
Sync (create, update and delete) changes from input configuration
kongctl sync -f konnect.yaml
Preview proposed changes from a generated plan
kongctl diff --plan plan.json
Frequently asked questions
I use decK to configure Kong Gateway, why should I care about kongctl?
Currently decK and kongctl are complementary, but serve different purposes:
- decK was designed to manage Kong Gateway configuration (Services, Routes, plugins, and Consumers), both on-premises and in Konnect.
- kongctl is designed for managing Konnect API platform resources (APIs, Dev Portals, application auth strategies, control planes)
decK works with Konnect but targets a single control plane. kongctl operates at a higher level and allows you to manage the full set of API Platform resources.
If you’re using Konnect and Kong Gateway, you might use both tools: kongctl for platform-level resources and decK for gateway configuration within control planes.
kongctl supports integrating the tools together by coordinating execution of deck commands in proper sequence of kongctl resource management. See kongctl and deck for details on using the tools together.
Can I run multiple kongctl processes at the same time?
Yes, but with caution. Since kongctl’s declarative engine is stateless and calculates changes by querying live Konnect resources, concurrent processes operating on the same resources could conflict. Use namespace isolation to separate resources managed by different processes or teams.
Is kongctl production-ready?
kongctl is currently in Beta release stage. This means it’s provided without warranty and interfaces may change. It’s designed for evaluation and testing, with production-readiness coming in future releases. See the GitHub releases page for current status.
What resources can kongctl manage declaratively?
The list of Konnect resources supported is growing. The current list includes (but not limited to):
- APIs: Including versions, publications, implementations, and documents
- Dev Portals: Including pages, teams, snippets, customizations, authentication strategies, and custom domains
- Control planes: For Kong Gateway control plane management and decK integration
Support for additional resource types is planned for future releases.
How does kongctl authentication work?
kongctl supports two authentication methods:
-
Device Flow (Recommended): Run
kongctl loginto authenticate via your browser. Tokens are stored locally and refreshed automatically. -
Personal Access Token: Use the
--patflag orKONGCTL_DEFAULT_KONNECT_PATenvironment variable for automation scenarios like CI/CD pipelines.
Configuration and device flow authentication credentials are stored in $XDG_CONFIG_HOME/kongctl/ (typically ~/.config/kongctl/).
Can I use kongctl in CI/CD pipelines?
Yes. kongctl is designed for CI/CD integration:
- Use personal access tokens for non-interactive authentication
- Generate plan artifacts in pull requests for review before applying changes
- Store plan JSON files in version control for audit trails
- Use namespace isolation to separate environments
- Implement approval gates for production deployments
How is kongctl different from the Konnect APIs?
The Konnect REST APIs are imperative style direct APIs requiring you to coordinate your changes appropriately.
kongctl provides:
- A command-line interface with human-friendly output formats
- Declarative configuration with plan-based workflows
- Interactive terminal UI for resource exploration