CLI
CLI Command Groups
Every public verdictan command, grouped by task, with a link to the page that covers it in depth. New to the CLI? Start with the CLI Overview to install it and sign in. For the exact options of any command, run it with --help.
Bootstrap, auth, and diagnostics
| Command | Use |
|---|---|
verdictan init | Create a starter policy-config.yaml and one example policy test in a new project |
verdictan auth login | Sign in and store a CLI session for one profile |
verdictan auth logout | Delete the stored session of one profile |
verdictan auth whoami | Show the identity and permissions that the API resolves |
verdictan auth token create | Create a scoped API token with IAM role bindings |
verdictan auth token list | List issued API tokens |
verdictan auth token revoke | Revoke one API token |
verdictan doctor | Examine API connectivity, the config file, the state directory, and local gateway instances |
verdictan config validate | Validate the structure of a policy config without a gateway runtime |
Details: verdictan init, verdictan auth, verdictan doctor, and verdictan config validate.
Policy authoring and rollout
| Command | Use |
|---|---|
verdictan policy lint | Validate a policy config or an IAM policy document |
verdictan policy test | Run pack tests and inline testing suites |
verdictan policy push | Validate a file, save a configuration version, and deploy it through an agent. Requires CLI 0.1.14 or later. |
verdictan policy deploy | Request a rollout from a source gateway to target gateways. The current API rejects the gateways with Unknown gateway target. Deploy in Configurations instead. |
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 remote IAM policies |
verdictan policy export | Export remote IAM policies to YAML or JSON |
verdictan policy works on two kinds of document. For a gateway's policy-config.yaml, use lint, test, push, and deploy. For IAM policy documents, use lint, diff, apply, evaluate, and export. Manage configuration in a file walks through authoring and verifying a policy config end to end.
Details: Policy Lifecycle, verdictan policy lint, and verdictan policy test.
Gateway runtime and lifecycle
| Command | Use |
|---|---|
verdictan gateway run | Start a gateway in the calling process for the supported request families |
verdictan gateway check | Resolve the config, provider credentials, routing, and policy chain without a server |
verdictan gateway create | Create a local supervisor definition with listen and upstream settings |
verdictan gateway list | List local gateways, or remote gateways with --remote |
verdictan gateway inspect | Examine one local gateway and its recent lifecycle history |
verdictan gateway config | Read the config endpoint of an active gateway by URL |
verdictan gateway reload | Send a reload request to an active gateway by URL |
verdictan gateway diff | Compare the active state of a named gateway with its saved service state |
verdictan gateway revert | Send a revert request to an active gateway by URL |
verdictan gateway reconcile | Reconcile one 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 the service-manager status of 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, or examine a runtime binary upgrade. Restore the previous version if necessary |
Details: verdictan gateway run, verdictan gateway, and verdictan config validate.
Profiles, regions, and locality
| Command | Use |
|---|---|
verdictan configure set region <region> --profile <profile> | Save a default region for one profile in ~/.verdictan/config.yaml |
verdictan configure get region --profile <profile> | Read the default region of one profile |
verdictan configure list-profiles | Show the profile names from the config file and stored credentials |
verdictan regions list | List the 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 verdictan regions use |
verdictan regions current | Show the resolved region, its source, the API endpoint, and the requested scope |
verdictan regions status | Show the status of each region |
For API-backed commands, use the command's own --region <region> option. The top-level verdictan --region <region> ... form exists for compatibility with the local gateway and runtime, which read the region from the process environment. verdictan regions list also accepts --enabled, --disabled, --group <group_key>, --sovereignty-class <class>, and --json.
A profile's region only chooses where API-backed CLI commands go. Gateway and provider locality live in policy-config.yaml, and a profile default never overrides them.
verdictan config show, config migrate, and config diff are not public commands. Use verdictan configure ... for profile defaults, verdictan regions ... for locality, and a specific diff such as verdictan gateway diff or verdictan policy diff.
Details: verdictan regions and Regions Overview.
MCP on a published hostname
MCP is not a verdictan subcommand. The gateway serves it at /mcp on a published agent hostname. Gateway MCP Surface covers the transport, its limits, and how hosted MCP differs from runtime bridge targets and declarative tool-server metadata.
Events, exports, and escalations
| Command | Use |
|---|---|
verdictan events tail | Query recent governance events from the control plane |
verdictan events export | Export event evidence as CSV or JSON |
verdictan trail lookup | Query Trail records by request ID or audit filters |
verdictan trail verify | Verify a bounded Trail window, with --deep for event hashes, sequences, and links |
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 that policy outcomes generated |
verdictan escalation get | Examine one escalation |
verdictan escalation claim | Claim an escalation for triage |
verdictan escalation unclaim | Release a claimed escalation |
verdictan escalation resolve | Resolve an escalation with the selected outcome |
Details: verdictan events, verdictan trail, verdictan export-jobs, and verdictan escalation.
History, secrets, cache, and control
| Command | Use |
|---|---|
verdictan history list-sessions, get-session | List and examine governed History sessions |
verdictan history export, tag, search, share, replay, stats | Export, organize, search, replay, and summarize History |
verdictan history learn | Request server-side learning for one 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 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 of 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 control plane |
verdictan control export | Export the active remote control state into a manifest |
Two groups have similar names: verdictan secret ... manages secret records hosted in Verdictan, and verdictan secrets ... checks the keychain and environment credentials on this machine. Run verdictan cache ... in the same cache environment as the gateway. Always run verdictan control plan before apply, and plan --prune before apply --prune, reading the proposed deletions.
Details: verdictan history, Manage Secrets and Credentials, verdictan cache, and verdictan control.
IAM, users, teams, roles, policies, and agents
| Command | Use |
|---|---|
verdictan user ... | Manage user inventory, invitations, lifecycle, and direct role assignment |
verdictan team ... | Manage teams, membership, and team-level role grants |
verdictan role ... | Manage roles, policy assignment, and effective-action inspection |
verdictan iam policy ... | Manage IAM policies for role assignments |
verdictan agent list, get, create, update, delete | Manage agent records |
verdictan agent link-gateway, unlink-gateway | Bind agents to gateway runtimes |
Details: IAM, Members, Teams, and Roles, verdictan control, and verdictan agent.
Spend, budgets, provider budgets, and API tokens
| Command | Use |
|---|---|
verdictan spend summary | Report aggregate spend |
verdictan spend budget ... | Manage organization, team, user, and key budgets |
verdictan spend provider-budget ... | Manage provider-specific budget ceilings |
verdictan token ... | Manage the governed API token lifecycle: create, update, clone, revoke, rotate, validate, and code exchange |
Details: Spend, Budgets, and API Tokens.
Runtime feature guides
Much of the gateway's behavior is set in policy-config.yaml rather than by a command. These guides cover it:
| Feature | Where to read more |
|---|---|
| Streaming compatibility and chunked passthrough | Streaming and 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 | Provider 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 | verdictan cache |
| Provider routing, fallback, and model groups | Provider Configuration and Data Routing Policy |
| Rate limits | Rate Limit 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 and Policy Configuration Overview |
Next steps
- Install the Gateway: get the CLI.
- verdictan gateway run: start a gateway from a policy config.
- Policy Lifecycle: author and roll out a policy config.