verdictan regions

Use verdictan regions to store a default region for a CLI profile and to check which region the CLI resolves. use and switch write the default. current shows the result and its source. list and status query the region catalog of the API.

The default region is stored in the CLI config file, under profiles.<profile>.default_region. verdictan configure set region <region> --profile <name> writes the same entry.

Set and check the default region

Store eu-west for a profile, then check the result:

verdictan regions use eu-west --profile work
verdictan regions current --profile work

use prints the file that it changed:

Configured region set to 'eu-west' in /home/user/.verdictan/config.yaml

The file then contains this entry. Other keys in the file do not change:

~/.verdictan/config.yaml

profiles:
  work:
    default_region: eu-west

current shows the resolved region, its source, and the precedence chain:

current region: eu-west
source: profile 'work' default_region
profile: work
resolved api endpoint: https://api.verdictan.com
requested region scope: regional

precedence chain:
  1. VERDICTAN_REGION env:      -
  2. profile default region:     eu-west (active)
  3. declarative config region:  -

Check the region and the API endpoint. Storing a region does not change the API URL and does not move resources between regions.

Usage

verdictan regions use <region> [--profile <name>] [--config <path>]
verdictan regions switch <region> [--profile <name>] [--config <path>]
verdictan regions current [--profile <name>] [--config <path>] [--api-url <url>] [--json]
verdictan regions list [--enabled | --disabled] [--group <key>] [--sovereignty-class <class>] [--api-url <url>] [--json]
verdictan regions status [--api-url <url>] [--json]

Options

Flag	Applies to	Description
<region>	use, switch	Mandatory region key. The CLI accepts global, or two lowercase words with a hyphen between them, such as eu-west.
--profile <name>	use, switch, current, list	Profile to read or write. The default is default. For current and list, the default profile is the profile value in the config file, if it has one.
--config <path>	all	CLI config file. Without it, the CLI uses VERDICTAN_CONFIG, then ~/.verdictan/config.yaml. use creates the file when it does not exist.
--api-url <url>	current, list, status	API base URL.
--enabled	list	Show only regions with the active lifecycle.
--disabled	list	Show only regions that are not active.
--group <key>	list	Show only regions in one primary region group. Uses the authenticated organization catalog.
--sovereignty-class <class>	list	Show only regions in one sovereignty class. The match ignores case.
--json	current, list, status	Print JSON.

switch is an alias for use. These flags belong to the regions group, so you can also put them before the subcommand, for example verdictan regions --profile work current.

Examples

# Store a default region for the default profile
verdictan regions use eu-west

# Store a default region in a project-specific config file
verdictan regions switch us-east --profile ci --config ./verdictan.yaml

# Show the resolved region as JSON
verdictan regions current --profile work --json

JSON output of current:

{
  "default_region": "eu-west",
  "profile": "work",
  "region": "eu-west",
  "requested_region": "eu-west",
  "requested_region_scope": "regional",
  "resolved_api_endpoint": "https://api.verdictan.com",
  "resolved_region": "eu-west",
  "resolved_region_source": "profile 'work' default_region",
  "source": "profile 'work' default_region"
}

requested_region_scope is global when the region is global, and regional for every other key. When the CLI finds no region, current prints no region configured, the profile, the API endpoint, and the commands that set a region. In JSON, the region fields are null. Both cases exit with 0.

Query the region catalog

verdictan regions list --enabled
verdictan regions status

list and status use the configured API URL and credential. You can set VERDICTAN_API_TOKEN or use the session from verdictan auth login. The commands read GET /v1/regions and use its cells array. The API limits the result to regions visible to your organization.

list prints the region key, display name, sovereignty class, lifecycle, currency, and API endpoint. The filters select records from this catalog. status prints the same catalog as one block per region. It does not probe the network or measure gateway health. A field that the API does not return shows as -.

Region precedence

The CLI uses two different region chains.

verdictan regions current shows the process-wide region that local gateway and runtime surfaces read:

1. VERDICTAN_REGION. The top-level --region <region> option sets this variable for the process.
2. profiles.<profile>.default_region in the CLI config file.
3. The root-level default_region in the same file. current labels this source declarative config.

Commands that resolve the CLI config for API calls use:

1. The --region <region> value that the command receives.
2. profiles.<profile>.default_region.
3. The root-level default_region.

This second chain does not read VERDICTAN_REGION.

note

A CLI region does not change VERDICTAN_API_URL. It does not override the locality settings in policy-config.yaml for gateway or provider routing.

Limits and failure behavior

Condition	Result
use or switch with a key in another format	Stops with invalid region slug '<key>': expected format like 'eu-west' or 'us-east' and exit code 2.
use or switch with a key that is not in the catalog	The CLI stores it. It does not check the key against the catalog.
--config points to a file that does not exist, for current or list	Stops with failed to read config file <path>: ... and exit code 2.
list --enabled --disabled	Stops with `verdictan regions list` cannot combine --enabled and --disabled and exit code 2.
list or status without a credential	Stops with a sign-in error. Set VERDICTAN_API_TOKEN or run verdictan auth login.
list with filters that match no region	Prints no regions matched filters and exits with 0.
--api-token on any command	Stops with command-line token flags have been removed; set VERDICTAN_API_TOKEN or use a stored profile instead.

Next steps

• Select a Region: learn about region groups, sovereignty classes, and locality.
• CLI Overview: see how profiles and regions fit into the CLI setup.
• verdictan auth: set up the credential for API commands.