CLI scripting
Use the CLI command references to select the inputs for each operation. This page explains the shared rules for scripts. Start with Authentication and Regions before you automate API changes.
Input rules
verdictan --helplists command groups. Each command accepts--helpor-h.verdictan --versionorverdictan -Vprints the installed version.- A value option accepts
--option valueor--option=value. Quote values that contain spaces or shell characters. Use--to end option parsing before a positional value that starts with a hyphen. - A switch such as
--jsonor--yestakes no value. Do not write--json trueor--yes=false. - Repeat an option only when its reference says it is repeatable. Comma-separated values work only where the reference documents a comma delimiter. Repeating a single-value option is an error.
- Required input in a table means the parser requires it. Read the command's conditions too: for example,
history shareneeds exactly one recipient selector, andpolicy pushneeds a gateway or agent selector. --lang TAGis a global option. The CLI prints English. A non-English value produces a warning on standard error.VERDICTAN_LANGhas the same behavior; the flag takes priority.- The global
--region REGIONselects a process region. Commands that expose their own region input can apply that value to the API operation. Region selection does not change the API origin. Use the command's documented placement and region rules.
The CLI has no shell-completion command. Use the installed command's help when you need the options for that version.
Connection and profile selection
For commands that use the normal API connection:
| Setting | Selection order |
|---|---|
| Connection file | --config, VERDICTAN_CONFIG, then ~/.verdictan/config.yaml when it exists |
| API URL | --api-url, VERDICTAN_API_URL, connection-file api_url, saved session URL, then https://api.verdictan.com |
| Credential | VERDICTAN_API_TOKEN, connection-file api_token, then the selected saved terminal session |
| Region | Explicit region, selected profile's default_region, then root default_region; command-specific rules can also apply |
Most API commands declare --profile default. Pass --profile work explicitly when your script needs another account profile. A root profile value does not replace an explicit or command-default profile. ACP defaults to kalkidan and uses the desktop account connection; it does not use the normal plaintext terminal token file. See Managed coding agents.
policy-config.yaml describes gateway behavior. It is separate from the CLI connection file. A command such as gateway check --config policy-config.yaml uses that input as a policy file; read each command's table before reusing a flag.
Never put raw credentials in command arguments. The CLI rejects --api-token, --admin-token, --gateway-key, and --upstream-api-key. Use the documented environment or keyring source. token validate reads a token from standard input; terminal input requires --force-tty.
Output and files
Use --json only when the command documents it. JSON is normally formatted across multiple lines and ends with a newline. Diagnostic messages and warnings use standard error. Keep the streams separate if another program reads standard output.
Some commands have their own output contract:
| Command | Output rule |
|---|---|
events tail --follow --json | A sequence of formatted event objects. It is not a JSON Lines stream or one enclosing JSON array. |
auth desktop, gateway supervise | Protocol JSON Lines on standard output. The supervising client must implement the protocol. |
events export, export-jobs download | Raw response bytes on standard output. Save them with shell redirection. |
history export | Selected format on standard output, or the file given by --output. |
history condense --output | Artifact JSON in the file. The artifact is not also printed, including with --json. |
policy export | Writes --file in the selected format. There is no --json flag. |
trail export | Writes the required output file; a .gz suffix selects gzip. |
gateway config | JSON without a --json option. |
| Token creation, rotation, cloning, or OAuth code exchange | Can print a new credential. Store that output as a secret. |
Example export:
verdictan events export --since 1d --format csv > events.csvSet resource IDs and file paths in example templates before use. A placeholder is not a resource lookup. A list or report can be paginated; read the command's limits before treating it as a complete inventory.
Confirmations and changes
Confirmation rules differ by command. Commands that require --yes stop without it. cache clear can ask interactively. policy apply and control apply ask in text mode unless --yes is present, but JSON mode applies without that prompt.
Read a plan before an apply operation, especially with --prune, which can delete resources. A successful assignment or service-start command does not prove that a running gateway has applied the configuration. Read the resulting state and decision evidence for that workflow.
Exit codes and result fields
| Exit code | Meaning |
|---|---|
0 | The command completed. Inspect its result to determine the product outcome. |
2 | Invalid input or a command-level check failure |
3 | Authentication or authorization failure |
4 | Network, API-response, or response-decoding failure |
5 | Internal CLI error |
6 | Gateway operation error |
The shared API client classifies HTTP 401 and 403 as authentication errors, and 409 and 422 as user errors. Other unsuccessful statuses, including 404, normally use the network/API error category. Individual commands can handle a status themselves.
Exit 0 does not always mean that a check passed:
| Result | Read this field or outcome |
|---|---|
config validate --json | valid and errors; range findings can exit 0 |
doctor --json | Every check's status; completed failed checks can exit 0 |
policy apply --json, control apply --json | Failed operation records as well as the process status |
gateway reconcile --json | Every results[].healthy value |
token validate --json | valid |
policy evaluate --json | The allow or deny simulation result; a deny is not a command error |
models status --json | Each artifact's installed, missing, or invalid state |
policy test returns exit 2 for failing cases after it prints the result, including in JSON mode. trail verify returns an error for invalid evidence or an empty verification window, including in JSON mode.
Timeouts and retries
The shared control-plane JSON client uses a 10-second connection timeout and a 30-second request timeout. Eligible JSON GET requests can retry transient connection failures and HTTP 429, 500, 502, 503, or 504, with up to three retries. Other operations and raw-byte downloads do not all use that retry path.
Commands with polling have their own wait controls, such as export jobs and policy deployment. A local wait timeout does not cancel a remote operation. Check its state before repeating a mutation. Use the IDs returned by the API to find an operation that might already have succeeded.
Next steps
- Command groups: select a command reference.
- Environment variables: configure a terminal, service, or container.
- Authentication: credentials and saved sessions.