CLI Overview
Use the verdictan CLI to manage the public Verdictan workflow from the terminal.
Start here
| Task | Start with |
|---|---|
| Install the CLI | Install the Gateway |
| Bootstrap a config | verdictan init |
| Validate config and policy | Config Validation and Policy Lifecycle |
| Run a gateway | verdictan gateway run |
| Manage profiles and regions | Regions Overview and Region Commands |
| Connect an MCP client to Verdictan | Gateway MCP Surface |
| Examine runtime outcomes | verdictan events and verdictan export-jobs |
| Review immutable audit evidence | verdictan trail |
| Manage tokens and auth | verdictan auth |
| Review spend and budgets | verdictan spend |
Public command groups
| Workflow | Commands |
|---|---|
| Bootstrap and diagnostics | verdictan init, verdictan doctor, verdictan config validate |
| Auth and tokens | verdictan auth ..., verdictan token ... |
| Policy authoring | Use verdictan policy lint/test/push/deploy for runtime config. Use verdictan policy diff/apply/evaluate/export for IAM. |
| Gateway runtime | verdictan gateway ... |
| Profiles, regions, and locality | verdictan configure ..., verdictan regions ..., verdictan --region ... |
| Published-hostname MCP | Gateway-hosted /mcp surface on a published agent hostname |
| Events and evidence | verdictan events ..., verdictan trail ..., verdictan export-jobs ..., verdictan escalation ... |
| Cache and secrets | verdictan cache ..., verdictan secret ..., verdictan secrets ... |
| IAM and agents | verdictan user ..., verdictan team ..., verdictan role ..., verdictan iam policy ..., verdictan agent ... |
| Spend and budgets | verdictan spend summary, verdictan spend budget ..., verdictan spend provider-budget ... |
| Declarative control plane | verdictan control plan/apply/export |
This site lists customer command groups that are available for public use.
Typical public workflow
export VERDICTAN_API_URL="https://api.verdictan.com"
export VERDICTAN_API_TOKEN="vdt_your_authorized_token"
verdictan init
verdictan config validate --file policy-config.yaml
verdictan policy lint --file policy-config.yaml
verdictan policy test --json
verdictan gateway check --config policy-config.yaml
# Add a provider target and its referenced secret before serving model traffic.
# Replace docs-demo with an existing control-plane agent name.
verdictan gateway run --agent docs-demo --listen 127.0.0.1:41002 --policy-config policy-config.yaml
verdictan events tail --since 5m --json
Shared global options
--lang and the compatibility --region shim are top-level global options.
The other flags below are command-specific. If the selected subcommand
documents one of these flags, you can use it.
| Flag | Meaning |
|---|---|
--lang | Select localized CLI output, overriding VERDICTAN_LANG and the OS locale |
--json | If the command supports it, request JSON output. |
--config | If the command supports it, select a local CLI config file. |
--api-url | Override the API base URL on supported API-backed commands |
--profile | Select a named CLI profile on supported API-backed commands |
--region | Set the process region for local runtime surfaces that use the compatibility shim. API commands that support regions have their own --region option. |
The default CLI config file path is ~/.verdictan/config.yaml.
For API authentication, use VERDICTAN_API_TOKEN or a stored profile from
verdictan auth login. The CLI no longer accepts API tokens as command-line flags.
Use ~/.verdictan/config.yaml for CLI profile defaults, such as the requested
region. Use policy-config.yaml for gateway runtime and provider routing. This
policy config includes behavior that uses locality. verdictan regions current helps you
examine the profile default. It does not rewrite policy-config.yaml.
Key environment variables
| Variable | Purpose |
|---|---|
VERDICTAN_API_URL | Verdictan API base URL |
VERDICTAN_API_TOKEN | Use as a direct CLI credential or connected-runtime service credential. It is not automatically the application bearer token for model requests. |
VERDICTAN_REGION | Compatibility process region for surfaces that continue to use it. It is not the API-command region fallback. |
VERDICTAN_OPENAI_API_KEY | Recommended OpenAI provider secret name. Reference this environment name through secret_key_ref.env. |
VERDICTAN_CONFIG | Path to a local CLI config file |
The gateway resolves provider credentials only from the declared environment or
secret-store name that the target declares. The gateway does not implicitly fall back
to generic provider variables such as OPENAI_API_KEY.