Skip to main content

kt regions

Use kt regions to discover available regions and inspect which region the CLI is currently using.

For profile-scoped defaults, the preferred write path is kt configure.

Commands​

List published regions​

kt regions list
kt regions list --json
kt regions list --enabled
kt regions list --group eu
kt regions list --sovereignty-class sovereign

Lists the regions returned by the region discovery API, including locality metadata and API endpoints. Without a token, this uses the public catalog. With a token, it uses the organization region catalog. --group requires authenticated organization metadata, and --enabled cannot be combined with --disabled.

Set the default region for a profile​

kt configure set region eu-west --profile default
kt configure get region --profile default
kt configure list-profiles

This stores the selected region in ~/.keeptrusts/config.yaml.

Alias: kt regions use​

kt regions use eu-west --profile default

kt regions use writes the same profile-scoped default_region entry.

Alias: switch​

kt regions switch us-east --profile default

switch is an alias for use.

Show the current resolved region​

kt regions current

Use this when you want to see both the resolved region and the precedence source that supplied it.

Show detailed region status​

kt regions status

This renders the status fields published by the regions endpoint. Gateway count, active-session count, and heartbeat fields are shown when the endpoint provides them.

Per-command override​

For API-backed commands that expose their own region option, put --region on that command:

kt events tail --region us-east

The top-level form, kt --region us-east ..., is a compatibility shim for local gateway/runtime surfaces that still read process-wide region context. It is not the region fallback used by Config::resolve for API-backed commands.

Precedence​

For ordinary API-backed commands, region resolution follows this order:

  1. The command's --region <region> option
  2. profiles.<profile>.default_region in ~/.keeptrusts/config.yaml
  3. the legacy root-level default_region field in the same file

KEEPTRUSTS_REGION is not a fallback in that API-command resolution path.

kt regions current is a diagnostic for the older process-wide context. It shows KEEPTRUSTS_REGION first (including a value populated by the top-level kt --region shim), then the profile default, then the legacy root-level default. It also prints the separately resolved API endpoint; selecting a region does not synthesize or replace that endpoint.

Declarative-config precedence

kt regions current explains the CLI-requested region. It does not override locality already declared in policy-config.yaml for gateway or provider routing, and it does not change the locality implied by a published hostname.

Region behavior

CLI endpoint selection and provider routing are separate. A command's region header does not rewrite KEEPTRUSTS_API_URL, and provider fallback behavior is controlled by the gateway's provider config rather than by kt regions.

If no region is configured, kt regions current reports no region configured. API-backed commands can still call their configured API endpoint without a region override; whether a particular operation requires locality is an API contract decision.

Next steps​