CLI Command Groups

This page lists the public verdictan command surface. Use it to find the correct command family. It also gives you a high-level map of the documented CLI.

Bootstrap, auth, and diagnostics

Command	Purpose
`verdictan init`	Scaffold a starter `policy-config.yaml` and example tests for a new local project
`verdictan auth login`	Sign in and store a CLI session for reuse
`verdictan auth logout`	Remove stored session credentials for the active profile
`verdictan auth whoami`	Show the active identity and API access context
`verdictan auth token create`	Create a scoped automation token that uses IAM role bindings
`verdictan auth token list`	List issued auth tokens
`verdictan auth token revoke`	Revoke a previously issued auth token
`verdictan doctor`	Report API connectivity, config readability, state-directory access, and local supervisor records
`verdictan config validate`	Parse and validate a declarative gateway configuration without starting a runtime

Policy authoring and rollout

Command	Purpose
`verdictan policy lint`	Validate a runtime config or IAM policy document
`verdictan policy test`	Run local pack tests and inline `testing` suites
`verdictan policy push`	Upload a policy config as a new version for a gateway
`verdictan policy deploy`	Roll out a source policy version to one or more target gateways and verify application
`verdictan policy diff`	Calculate a dry-run reconcile plan for IAM policy documents
`verdictan policy apply`	Reconcile reviewed IAM policy documents to the control plane
`verdictan policy evaluate`	Simulate an action and resource VDT against local or selected remote IAM policies
`verdictan policy export`	Export selected or all remote IAM policies to YAML or JSON

Use this group for the authoring loop:

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
verdictan policy push --file policy-config.yaml --gateway-id local-gateway

The command family manages two document types. Runtime policy-config.yaml uses lint, test, push, and deploy. IAM policy documents use lint, diff, apply, evaluate, and export. See Policy Lifecycle before you automate one of these paths.

Gateway runtime and lifecycle

Command	Purpose
`verdictan gateway run`	Start a local governance gateway for the supported public request families
`verdictan gateway check`	Resolve config, provider credentials, routing, and the policy chain without starting a server
`verdictan gateway create`	Create a local supervisor definition with selected listen and upstream settings
`verdictan gateway list`	List local gateways, or remote gateways with `--remote`
`verdictan gateway inspect`	Examine a named local gateway and optional recent lifecycle history
`verdictan gateway config`	Query a running gateway config endpoint by URL
`verdictan gateway reload`	Send a reload request to a running gateway at a specified URL
`verdictan gateway diff`	Compare the active named gateway state with its saved local service state
`verdictan gateway revert`	Send a revert request to a running gateway at a specified URL
`verdictan gateway reconcile`	Reconcile a named gateway, or all known gateways with `--all`
`verdictan gateway install`	Install a local gateway as a user service
`verdictan gateway start`	Start an installed gateway service
`verdictan gateway status`	Show service-manager status for an installed gateway
`verdictan gateway stop`	Stop an installed gateway service
`verdictan gateway uninstall`	Remove the installed gateway service definition
`verdictan gateway upgrade plan/apply/status/rollback`	Plan, apply, examine, or roll back a local runtime binary upgrade

Related guides:

Profiles, regions, and locality

Command	Purpose
`verdictan configure set region <region> --profile <profile>`	Save a profile-scoped default region in `~/.verdictan/config.yaml`
`verdictan configure get region --profile <profile>`	Read the configured default region for one profile
`verdictan configure list-profiles`	Show known profile names from config and stored credentials
`verdictan regions list`	List available regions with sovereignty class and API endpoints
`verdictan regions use`	Write the default region for the active CLI profile
`verdictan regions switch`	Alias for `use`
`verdictan regions current`	Show the resolved region, winning source, resolved API endpoint, and requested scope
`verdictan regions status`	Show detailed status for each region

Use a command's own --region <region> option for API-backed operations. The top-level verdictan --region <region> ... form is a compatibility shim for local gateway/runtime surfaces that continue to read process-wide context.

verdictan regions list also supports --enabled, --disabled, --group <group_key>, --sovereignty-class <class>, and --json.

Removed config commands

verdictan config show, verdictan config migrate, and verdictan config diff are no longer public CLI commands. Use verdictan configure ... for profile defaults. Use verdictan regions ... to examine locality. Use a command-specific diff operation, such as verdictan gateway diff or verdictan policy diff, only for an available operation.

Declarative-config precedence

Use verdictan configure ... and verdictan regions ... to manage the requested region for API-backed CLI commands. Use policy-config.yaml for gateway and provider locality. The CLI profile default does not override the runtime routing in the policy config.

Published-hostname MCP

This surface is not a verdictan subcommand. The gateway supports MCP directly at a published agent hostname on /mcp.

Use Gateway MCP Surface for transport details and capability limits. It also gives the differences between hosted MCP, runtime bridge targets, and declarative tool-server metadata.

Events, exports, and escalations

Command	Purpose
`verdictan events tail`	Query recent event records from the Verdictan API
`verdictan events export`	Export event data directly as CSV or JSON
`verdictan trail lookup`	Query immutable Trail events by request ID or audit filters
`verdictan trail verify`	Verify a nonempty bounded Trail window. The default verifies digest links. `--deep` also verifies event hashes, sequences, and links in the window.
`verdictan trail export`	Export a filtered Trail window to JSON, JSONL, CSV, or gzip
`verdictan export-jobs list`	List asynchronous export jobs
`verdictan export-jobs get`	Examine one export job and its state
`verdictan export-jobs create`	Queue a new evidence export job
`verdictan export-jobs download`	Download a completed export artifact
`verdictan escalation list`	List escalations generated by policy outcomes
`verdictan escalation get`	Examine a selected escalation
`verdictan escalation claim`	Claim an escalation for triage
`verdictan escalation unclaim`	Release a previously claimed escalation
`verdictan escalation resolve`	Mark an escalation resolved with the selected outcome

History, secrets, cache, and control

Command	Purpose
`verdictan history list-sessions/get-session`	Browse and examine governed History sessions
`verdictan history export/tag/search/share/replay/stats`	Export, organize, examine, replay, and summarize governed History
`verdictan history learn`	Request server-side learning for one selected History session, or preview its source entries
`verdictan history condense`	Generate a condensed session summary for review or handoff
`verdictan secret list/get/create/update/delete`	Manage hosted secret records without putting secret values on the command line
`verdictan secrets add/status`	Manage local credential resolution for provider targets
`verdictan cache stats/list/inspect/clear`	Examine or clear the response-cache backend selected by the active environment
`verdictan control plan`	Calculate a dry-run reconcile plan for a control manifest
`verdictan control apply`	Apply a control manifest to the Verdictan API
`verdictan control export`	Export active remote control state into a manifest

Workflow notes:

Use verdictan secret ... for hosted secret records.
Use verdictan secrets ... for checks of local keychain or environment credentials.
Use verdictan cache ... with the same gateway cache environment.
Detailed entry and counter views are filesystem-specific.
Before you apply a manifest, use verdictan control plan.
Pair each apply --prune with a reviewed plan --prune.

IAM, users, teams, roles, policies, and agents

Command	Purpose
`verdictan user ...`	User inventory, invitations, lifecycle, and direct role assignment
`verdictan team ...`	Team CRUD operations, membership, and team-level role grants
`verdictan role ...`	Role CRUD operations plus policy assignment and effective-action inspection
`verdictan iam policy ...`	Manage IAM policies for reuse
`verdictan agent list/get/create/update/delete`	Manage first-class agent records
`verdictan agent link-gateway/unlink-gateway`	Bind agents to gateway runtimes

Related guides:

Spend, budgets, provider budgets, and API tokens

Command	Purpose
`verdictan spend summary`	Aggregate spend reporting
`verdictan spend budget ...`	Org, team, user, or key budget management
`verdictan spend provider-budget ...`	Provider-specific budget ceilings
`verdictan token ...`	Governed API token lifecycle, including create, update, clone, revoke, rotate, validate, and code exchange

This group manages cost limits, bounded access, and customer gateway credential rotation.

Runtime feature guides

The CLI also controls gateway runtime behavior through policy-config.yaml and related declarative documents.

Feature	Where to read more
Streaming compatibility and chunked passthrough	Streaming & SSE
WebSocket proxy compatibility	WebSocket Gateway
Connected relay transport for NAT-bound gateways	Connected Gateway Relay
Cross-provider request and response translation	Format Translation
Fallback and failover routing	Providers Configuration and verdictan gateway run
Route-based targeting and chain overrides	Routes and Consumer Groups
Caching behavior and runtime defaults	Runtime Configuration
Cache inspection and maintenance	Gateway Response Cache
Provider routing, fallback, and model groups	Providers Configuration, Data Routing Policy
Rate limits	Rate Limits Configuration
Declarative policy schema and gateway config shape	Declarative Config Reference
Policy controls such as DLP, human oversight, tool validation, and audit logging	Policy Controls Catalog, Policies Overview

Bootstrap, auth, and diagnostics​

Policy authoring and rollout​

Gateway runtime and lifecycle​

Profiles, regions, and locality​

Published-hostname MCP​

Events, exports, and escalations​

History, secrets, cache, and control​

IAM, users, teams, roles, policies, and agents​

Spend, budgets, provider budgets, and API tokens​

Runtime feature guides​

Next steps​