kongctl diff

Uses: kongctl
Related Documentation
Incompatible with
on-prem

Display a preview of changes between current and desired state.

Examples

Preview changes in apply mode (CREATE and UPDATE only):

kongctl diff -f config.yaml --mode apply

Preview changes in sync mode (CREATE, UPDATE, and DELETE):

kongctl diff -f config.yaml --mode sync

Preview targeted deletions in delete mode (DELETE only for matching resources):

kongctl diff -f config.yaml --mode delete

Preview changes from a plan artifact:

kongctl diff --plan plan.json

Note: --mode can’t be used with --plan because mode is stored in the plan artifact metadata.

For UPDATE actions, the text diff shows only the fields that would be changed. JSON and YAML outputs expose the same detail in each change’s changed_fields object while keeping fields as the execution payload.

Subcommands

kongctl provides the following tools for viewing diffs:

Command

Description

kongctl diff konnect Show Konnect configuration diffs.

Command usage

Usage:
  kongctl diff [flags]
  kongctl diff [command]

Examples:
  # Preview changes from declarative configuration
  kongctl diff -f api.yaml
  
  # Preview changes using the explicit Konnect target form
  kongctl diff konnect -f api.yaml
  
  # Display differences from an existing plan artifact
  kongctl diff --plan plan.json

Available Commands:
  konnect     Display differences between current and desired Konnect state


Flags:
      --base-dir string                   Base directory boundary for !file resolution.
                                          Defaults to each -f source root (file: its parent dir, dir: the directory itself). For stdin, defaults to CWD.
                                          - Config path: [ konnect.declarative.base-dir ]
      --base-url string                   Base URL for Konnect API requests.
                                          - Config path: [ konnect.base-url ]
                                          - Default   : [ https://us.api.konghq.com ]
      --color-theme string                Configures the CLI UI/theme (prompt, tables, TUI elements).
                                          - Config path: [ color-theme ]
                                          - Examples   : [ auto, 3024_day, 3024_night, aardvark_blue, abernathy ]
                                          - Reference  : [ https://github.com/lrstanley/bubbletint/blob/master/DEFAULT_TINTS.md ] (default "auto")
      --config-file string                Path to the configuration file to load.
                                          - Default: [ $XDG_CONFIG_HOME/kongctl/config.yaml ]
  -f, --filename strings                  Filename or directory to files to use to create the resource (can specify multiple)
      --full-content                      Display full content for large fields instead of summary
  -h, --help                              help for diff
      --http-retry-backoff-factor float   Exponential backoff growth factor for retries (for example: 2.0).
                                          - Config path: [ konnect.http-retry-backoff-factor ]
      --http-retry-initial-interval int   Initial retry backoff interval in milliseconds (0 = use default).
                                          - Config path: [ konnect.http-retry-initial-interval ]
      --http-retry-max-attempts int       Maximum total attempts for retryable HTTP requests (0 = use default, 1 disables retries).
                                          - Config path: [ konnect.http-retry-max-attempts ]
      --http-retry-max-interval int       Maximum retry backoff interval in milliseconds (0 = use default).
                                          - Config path: [ konnect.http-retry-max-interval ]
      --http-retry-on-connection-errors   Retry selected retryable connection-level errors.
                                          - Config path: [ konnect.http-retry-on-connection-errors ]
      --log-file string                   Write execution logs to the specified file instead of STDERR.
                                          - Config path: [ log-file ]
      --log-level string                  Configures the logging level. Execution logs are written to STDERR.
                                          - Config path: [ log-level ]
                                          - Allowed    : [ trace|debug|info|warn|error ] (default "error")
      --mode string                       Diff mode (sync|apply|delete) (default "sync")
      --no-telemetry                      Disable telemetry for this command invocation. Overrides config and env.
                                          - Config path: [ telemetry.enabled ]
                                          - Env var    : [ KONGCTL_NO_TELEMETRY ]
                                          - Default    : [ false ]
  -o, --output string                     Configures the format of data written to STDOUT.
                                          - Config path: [ output ]
                                          - Allowed    : [ json|yaml|text ] (default "text")
      --pat string                        Konnect Personal Access Token (PAT) used to authenticate the CLI. 
                                          Setting this value overrides tokens obtained from the login command.
                                          - Config path: [ konnect.pat ]
      --plan string                       Path to existing plan file to display
  -p, --profile string                    Specify the profile to use for this command. (default "default")
  -R, --recursive                         Process the directory used in -f, --filename recursively
      --region string                     Konnect region identifier (for example "eu"). Used to construct the base URL when --base-url is not provided.
                                          - Config path: [ konnect.region ]
      --require-any-namespace             Require explicit namespace on all resources (via kongctl.namespace or _defaults.kongctl.namespace).
                                          Cannot be used with --require-namespace.
                                          - Config path: [ konnect.declarative.require-any-namespace ]
      --require-namespace strings         Require specific namespaces. Accepts comma-separated list or repeated flags.
                                          Cannot be used with --require-any-namespace.
                                          Examples:
                                            --require-namespace=foo                          # Allow only 'foo' namespace
                                            --require-namespace=foo,bar                      # Allow 'foo' or 'bar' (comma-separated)
                                            --require-namespace=foo --require-namespace=bar  # Allow 'foo' or 'bar' (repeated flags)
                                          - Config path: [ konnect.declarative.require-namespace ]

Use "kongctl diff [command] --help" for more information about a command.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!