Skip to main content

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 --help lists command groups. Each command accepts --help or -h. verdictan --version or verdictan -V prints the installed version.
  • A value option accepts --option value or --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 --json or --yes takes no value. Do not write --json true or --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 share needs exactly one recipient selector, and policy push needs a gateway or agent selector.
  • --lang TAG is a global option. The CLI prints English. A non-English value produces a warning on standard error. VERDICTAN_LANG has the same behavior; the flag takes priority.
  • The global --region REGION selects 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:

SettingSelection 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
CredentialVERDICTAN_API_TOKEN, connection-file api_token, then the selected saved terminal session
RegionExplicit 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:

CommandOutput rule
events tail --follow --jsonA sequence of formatted event objects. It is not a JSON Lines stream or one enclosing JSON array.
auth desktop, gateway superviseProtocol JSON Lines on standard output. The supervising client must implement the protocol.
events export, export-jobs downloadRaw response bytes on standard output. Save them with shell redirection.
history exportSelected format on standard output, or the file given by --output.
history condense --outputArtifact JSON in the file. The artifact is not also printed, including with --json.
policy exportWrites --file in the selected format. There is no --json flag.
trail exportWrites the required output file; a .gz suffix selects gzip.
gateway configJSON without a --json option.
Token creation, rotation, cloning, or OAuth code exchangeCan print a new credential. Store that output as a secret.

Example export:

verdictan events export --since 1d --format csv > events.csv

Set 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 codeMeaning
0The command completed. Inspect its result to determine the product outcome.
2Invalid input or a command-level check failure
3Authentication or authorization failure
4Network, API-response, or response-decoding failure
5Internal CLI error
6Gateway 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:

ResultRead this field or outcome
config validate --jsonvalid and errors; range findings can exit 0
doctor --jsonEvery check's status; completed failed checks can exit 0
policy apply --json, control apply --jsonFailed operation records as well as the process status
gateway reconcile --jsonEvery results[].healthy value
token validate --jsonvalid
policy evaluate --jsonThe allow or deny simulation result; a deny is not a command error
models status --jsonEach 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​