CLI Overview

The verdictan CLI runs your gateway and manages Verdictan from a terminal: policy files, tokens, events, and audit trails. Check that it is installed:

verdictan --version

If the command is missing, install the CLI. To send your first model request, follow the quickstart.

Sign in and verify your identity

verdictan auth login
verdictan auth whoami

auth login finishes in your browser. Before any administrative command, check that whoami shows the right user and organization.

A VERDICTAN_API_TOKEN in the environment takes priority over your saved login. Keep a gateway runtime token in its own terminal so it doesn't replace your login by accident.

Select your next task

Task	Command
Start a configuration project	verdictan init
Check a policy file	verdictan policy lint
Test policy decisions	verdictan policy test
Run a gateway	verdictan gateway run
Diagnose a setup problem	verdictan doctor
Read request decisions	verdictan events
Manage tokens and spend	verdictan token and verdictan spend
Review administrative changes	verdictan trail

Commands lists every command group, including agents, teams, secrets, exports, and declarative management.

Find options for a command

Every command documents its own options:

verdictan gateway run --help
verdictan events tail --help

Options differ between commands, so trust the command's --help over memory.

Profiles and shared options

A profile stores connection defaults in ~/.verdictan/config.yaml; the default profile is default. This is separate from policy-config.yaml, which describes how a gateway behaves.

Many commands accept these options:

Option	Effect
--profile NAME	Use a saved profile
--api-url URL	Use another control-plane API endpoint
--config PATH	Use another CLI configuration file
--json	Print structured output
--lang TAG	Print output in another language
--region REGION	Target a region, in the position that command documents

Local runtime commands and API commands pick a region differently. See Select a Region.

Environment variables

Variable	Effect
VERDICTAN_API_URL	Control-plane API URL
VERDICTAN_API_TOKEN	Credential for CLI API calls, or for a connected gateway runtime
VERDICTAN_CONFIG	CLI configuration file path
VERDICTAN_LANG	Output language, unless --lang is set
VERDICTAN_REGION	A compatibility setting for the local runtime. API commands don't fall back to it.

Provider keys go in whichever variable a target's secret_key_ref.env names, such as OPENAI_API_KEY, in the gateway's environment.

Keep three credentials apart: the provider key, the gateway runtime token, and the application token. See Keep the credentials different.

The CLI refuses credentials on the command line: --api-token, --admin-token, and --gateway-key are rejected. Use an environment variable or your saved login.

Next steps

• Quickstart: send your first request.
• Manage configuration in a file: configure and test gateway behavior.
• Authentication: login sessions and tokens.