CLI

verdictan auth

Use verdictan auth to sign in to the Verdictan control plane, check which identity the API sees, and remove a stored session. Run it before you use commands that call the API, such as verdictan spend, verdictan policy push, or verdictan iam.

Before you start

A Verdictan user account in an organization.
For browser sign-in: a terminal session, and a browser on the same machine. The CLI receives the result on a local callback at http://127.0.0.1:<port>/callback.
For automation: an API token in VERDICTAN_API_TOKEN. You do not need verdictan auth login when this variable is set.

How the CLI selects a credential

API commands use the first credential that they find, in this order:

The VERDICTAN_API_TOKEN environment variable.
The stored session of the selected profile in ~/.verdictan/credentials.json.

The CLI does not accept a token on the command line. --api-token, --admin-token, and --gateway-key stop every command with this error:

Error: command-line token flags have been removed; set VERDICTAN_API_TOKEN or use a stored profile instead

The API URL comes from --api-url, then VERDICTAN_API_URL, then api_url in the config file, then the URL stored with the profile session. The default is https://api.verdictan.com. The config file is --config <path>, or VERDICTAN_CONFIG, or ~/.verdictan/config.yaml.

verdictan auth login
verdictan auth whoami

login opens the Console in your browser. Complete sign-in there. The terminal then prints the profile, organization, and role:

authenticated profile default
org: <org-name> (<org-id>)
role: <role>

whoami asks the API which identity the credential belongs to. Check the user and organization before you run administrative commands.

If whoami shows the wrong identity, check VERDICTAN_API_TOKEN. When it is set, it overrides the stored session. A gateway runtime token is not your personal session. Do not use it for administrative commands.

verdictan auth login signs in and stores the session for one profile.

Usage

verdictan auth login [--browser] [--console-url <url>] [--profile <name>] [--api-url <url>] [--config <path>] [--json]
verdictan auth login --email <email> --password <password> [--profile <name>] [--api-url <url>] [--json]

Options

Flag	Description
`--browser`	Use the browser sign-in flow. This is also the default when standard input is a terminal and you give no credentials.
`--console-url <url>`	Console base URL for browser sign-in. The default is `https://console.verdictan.com`.
`--email <email>`	Email for direct credential sign-in. Use it with `--password`.
`--password <password>`	Password for direct credential sign-in. Use it with `--email`.
`--profile <name>`	Profile that receives the session. The default is `default`.
`--api-url <url>`	API base URL.
`--config <path>`	Config file to read.
`--json`	Print the session summary as JSON.

The command selects the flow from the flags and the terminal:

Input	Result
No flags, standard input is a terminal	Browser sign-in.
`--browser`, standard input is a terminal	Browser sign-in.
`--email` and `--password`	Direct sign-in through `POST /v1/auth/login`.
Only one of `--email` and `--password`	Stops with `provide both --email and --password for direct credential login`.
`--browser` with `--email` or `--password`	Stops with `choose either --browser or --email/--password`.
Browser sign-in, standard input is not a terminal	Stops with `not a terminal — use VERDICTAN_API_TOKEN or a gateway key for non-interactive auth`.

The browser flow uses PKCE (S256) and a random state value:

The CLI starts a callback listener on 127.0.0.1 on a free port.
It opens <console-url>/auth/cli in the default browser. If the browser does not open, the CLI prints the URL. Open it yourself.
You sign in in the browser. The Console sends a one-time code to the local callback.
The CLI checks the state value and redeems the code at POST /v1/auth/handoff/redeem.

The CLI waits 5 minutes for the callback. After that it stops with Authentication timed out.

--console-url must be an absolute URL. It must use https, unless the host is localhost or 127.0.0.1. Its host must also match the API host: the same host, or console.<domain> when the API is api.<domain>. When the API runs on localhost, any console host is accepted. For a self-hosted deployment, set both URLs:

verdictan auth login --browser \
  --api-url https://api.example.com \
  --console-url https://console.example.com

Output

The CLI saves the session token, its expiry, the API URL, and the organization, project, role, team, and user details in ~/.verdictan/credentials.json, under the profile name. Other profiles in the file do not change.

Text output lists the profile, org, role, and teams when the user belongs to teams. With --json, the command prints authenticated, profile, org_id, org_name, project_id, role, team_ids, capabilities, and expires_at. It does not print the session token.

Examples

# Browser sign-in to the default profile
verdictan auth login

# Browser sign-in to a named profile
verdictan auth login --browser --profile work

# Sign in to a self-hosted deployment
verdictan auth login --browser \
  --api-url https://api.example.com \
  --console-url https://console.example.com

Direct credential sign-in puts the password in the process arguments, where shell history and process listings can show it. Use browser sign-in for people. Use VERDICTAN_API_TOKEN for automation.

verdictan auth logout

verdictan auth logout deletes the stored session of one profile from ~/.verdictan/credentials.json. It does not call the API. The session token stays valid on the server until it expires.

Usage

verdictan auth logout [--profile <name>] [--json]

Options

Flag	Description
`--profile <name>`	Profile to clear. The default is `default`.
`--json`	Print `logged_out` and `profile` as JSON. `logged_out` is `false` when the profile had no stored session.

Examples

verdictan auth logout
verdictan auth logout --profile work --json

The command prints cleared stored credentials for profile <name>, or no stored credentials for profile <name>. Both results exit with 0.

verdictan auth whoami

verdictan auth whoami calls GET /v1/whoami with the selected credential and prints the identity that the API resolved.

Usage

verdictan auth whoami [--profile <name>] [--api-url <url>] [--config <path>] [--json]

Options

Flag	Description
`--profile <name>`	Profile whose session to use when `VERDICTAN_API_TOKEN` is not set. The default is `default`.
`--api-url <url>`	API base URL.
`--config <path>`	Config file to read.
`--json`	Print the identity as JSON.

Examples

verdictan auth whoami
verdictan auth whoami --profile work --json

Text output has one line for each value:

Line	When it appears
`user: <email>`	The credential belongs to a user with an email.
`org: <name> (<id>)`	Always.
`project: <id>`	Always.
`role: <role>`	Always.
`auth_method: <method>`	Always.
`teams: <ids>`	The identity belongs to one or more teams.
`capabilities: <list>`	The identity has capabilities.
`resolved_roles: <role>:<binding>:<target>`	The API resolved one or more IAM roles.

The JSON output has user_id, email, display_name, org_id, org_name, project_id, role, auth_method, team_ids, capabilities, and resolved_roles. It contains only the fields that the CLI reads. It does not contain permissions from the API response.

verdictan auth token create

verdictan auth token create is the older, role-based token command. It calls POST /v1/tokens with a name, a principal type, and IAM role IDs.

The response contains the new token value. Copy it to your secret store. The API shows this value only at creation. Both text and JSON output include it, so keep the output out of shared logs.

Usage

verdictan auth token create --name <name> --role-id <role-id> [--role-id <role-id> ...] [OPTIONS]

Options

Flag	Description
`--name <name>`	Mandatory token name.
`--role-id <role-id>`	Mandatory IAM role UUID. Supply the flag once for each role.
`--scope <api_token\|gateway_runtime>`	Principal type of the new token. The default is `api_token`.
`--expires-at <rfc3339>`	Expiry timestamp. The API rejects a time that is not in the future.
`--team-id <id>`, `--subject-user-id <id>`	Set the team and user in the token `bindings` object. A `gateway_runtime` token must have `--team-id`.
`--profile <name>`, `--api-url <url>`, `--config <path>`	Standard profile and connection overrides.
`--json`	Print the token record and `token_value` as JSON.

The API also attaches its baseline access_key role to general-purpose tokens. For a gateway runtime credential, use --scope gateway_runtime --team-id <team-id>.

Examples

verdictan auth token create \
  --name "ci-deploy" \
  --role-id "replace-with-role-uuid" \
  --expires-at 2030-01-01T00:00:00Z

verdictan auth token list

verdictan auth token list calls GET /v1/tokens and prints one tab-separated line for each token: ID, principal type, prefix, and active or revoked.

Usage

verdictan auth token list [--profile <name>] [--api-url <url>] [--config <path>] [--json]

Options

Flag	Description
`--profile <name>`, `--api-url <url>`, `--config <path>`	Standard profile and connection overrides.
`--json`	Print the `tokens` array as JSON.

Examples

verdictan auth token list

The command follows the API cursors and prints all token pages. It reads the token ID from id. Use verdictan token list when you need its additional filters.

verdictan auth token revoke

verdictan auth token revoke calls DELETE /v1/tokens/<token-id>. The API sets the token to revoked and also revokes the unexpired JWTs that were exchanged from it. A token that does not exist or is already revoked returns 404.

Usage

verdictan auth token revoke --token-id <token-id> [--profile <name>] [--api-url <url>] [--config <path>] [--json]

Options

Flag	Description
`--token-id <token-id>`	Mandatory ID of the token to revoke.
`--profile <name>`, `--api-url <url>`, `--config <path>`	Standard profile and connection overrides.
`--json`	Print `revoked` and `token_id` as JSON.

Examples

verdictan auth token revoke --token-id "replace-with-token-id"
verdictan token get "replace-with-token-id" --json

The command accepts the API response 204 No Content as a successful revocation. It prints the revoked token ID, or {"revoked": true, "token_id": "..."} with --json.

verdictan token exchange-code

verdictan token exchange-code is part of the verdictan token group. It calls POST /v1/tokens/exchange-code and exchanges a PKCE authorization code from the Console consent flow for one API token. The endpoint does not need a stored session. The command does not start the consent flow, and it does not store the token in a profile.

Usage

verdictan token exchange-code --code <code> --code-verifier <verifier> --client-id <id> \
  --redirect-uri <uri> --token-name <name> --scope <org|team|project> [OPTIONS]

Options

Flag	Description
`--code <code>`	Mandatory authorization code from the consent flow.
`--code-verifier <verifier>`	Mandatory PKCE code verifier from the same flow.
`--client-id <id>`	Mandatory OAuth client ID.
`--redirect-uri <uri>`	Mandatory redirect URI from the authorization request.
`--token-name <name>`	Mandatory name of the new token.
`--purpose <purpose>`	Token purpose. The default is `general`.
`--scope <org\|team\|project>`	Mandatory scope.
`--team-id <id>`	Team for `--scope team`. Mandatory for that scope.
`--project-id <id>`	Project for `--scope project`. Mandatory for that scope. Supply the flag once for each project.
`--gateway-id <id>`, `--budget-id <id>`, `--provider <name>`, `--model-filter <model>`	Optional runtime bindings for the token. Supply `--model-filter` once for each model.
`--rate-limit-rpm <n>`, `--rate-limit-tpm <n>`, `--max-budget <amount>`, `--currency <code>`	Optional limits for the token.
`--api-url <url>`, `--config <path>`, `--profile <name>`	Standard connection overrides.
`--json`	Print the full exchange response as JSON.

The command checks the scope flags before it sends the request:

Scope	Rule	Error
`org`	No `--team-id` and no `--project-id`.	`org scope cannot be combined with --team-id or --project-id`
`team`	`--team-id` is mandatory. `--project-id` is not allowed.	`team scope requires --team-id`, `team scope cannot be combined with --project-id`
`project`	At least one `--project-id`. `--team-id` is not allowed.	`project scope requires at least one --project-id`, `project scope cannot be combined with --team-id`

Examples

verdictan token exchange-code \
  --code "replace-with-authorization-code" \
  --code-verifier "replace-with-pkce-code-verifier" \
  --client-id "replace-with-client-id" \
  --redirect-uri https://your-app.example.com/oauth/callback \
  --token-name "CLI Access Key" \
  --scope org

In text mode, the command prints only the raw token_value. The API shows it one time and sends the response with Cache-Control: no-store. Copy it to a secret manager immediately.

Limits and failure behavior

All verdictan auth commands use these exit codes:

Exit code	Meaning
`0`	Success.
`2`	Invalid input, such as a missing or conflicting flag, or an API `404` or `422`.
`3`	Authentication failure: no credential, an expired session, or an API `401` or `403`.
`4`	Network failure, or a response that the CLI cannot read.
`5`	Internal CLI error.

logout removes the local session only. To end access for a token, revoke it.
A stored session has an expiry. After it passes, API commands stop and ask you to sign in again.
whoami shows the identity and roles that the API resolved. More roles on a token do not bypass an authorization error.

Troubleshooting

Symptom	Cause	Fix
missing api token (set VERDICTAN_API_TOKEN or run `verdictan auth login`)	No environment token and no session for the profile	Run `verdictan auth login`, or set `VERDICTAN_API_TOKEN`. Check `--profile`.
stored api token has expired; run `verdictan auth login` again	The profile session has passed its expiry	Run `verdictan auth login --profile <name>`.
`not a terminal — use VERDICTAN_API_TOKEN or a gateway key for non-interactive auth`	Browser sign-in needs a terminal on standard input	Run the command in a terminal, or use `VERDICTAN_API_TOKEN` in automation.
`--console-url must match the console origin configured for this API`	The console host does not match the API host	Set `--api-url` and `--console-url` to the same deployment.
`--console-url must use https unless it points to localhost`	`--console-url` uses `http` for a remote host	Use an `https` URL.
`Authentication timed out`	The browser flow did not finish within 5 minutes	Run `verdictan auth login` again and complete sign-in in the browser.
`security error: state parameter mismatch`	The callback did not return the `state` value of this sign-in	Run `verdictan auth login` again. Do not reuse an old browser tab.
`invalid or expired authentication code (422)`	The one-time code was already used or has expired	Run `verdictan auth login` again.
`login failed (401)`	Wrong email or password	Check the credentials, or use browser sign-in.
`whoami` shows the wrong user	`VERDICTAN_API_TOKEN` overrides the stored session	Unset the variable, or select the correct `--profile`.

Next steps

Spend, Budgets, and API Tokens: create, narrow, rotate, and revoke API tokens with verdictan token.
verdictan init: create the first policy config after you sign in.
IAM, Members, Teams, and Roles: find role IDs and check role assignments.
OAuth Clients: set up the client and consent flow that issue authorization codes.

Before you start​

How the CLI selects a credential​

Sign in and verify​

verdictan auth login​

Usage​

Options​

Browser sign-in​

Output​

Examples​

verdictan auth logout​

Usage​

Options​

Examples​

verdictan auth whoami​

Usage​

Options​

Examples​

verdictan auth token create​

Usage​

Options​

Examples​

verdictan auth token list​

Usage​

Options​

Examples​

verdictan auth token revoke​

Usage​

Options​

Examples​

verdictan token exchange-code​

Usage​

Options​

Examples​

Limits and failure behavior​

Troubleshooting​

Next steps​

Before you start

How the CLI selects a credential

Sign in and verify

verdictan auth login

Usage

Options

Browser sign-in

Output

Examples

verdictan auth logout

Usage

Options

Examples

verdictan auth whoami

Usage

Options

Examples

verdictan auth token create

Usage

Options

Examples

verdictan auth token list

Usage

Options

Examples

verdictan auth token revoke

Usage

Options

Examples

verdictan token exchange-code

Usage

Options

Examples

Limits and failure behavior

Troubleshooting

Next steps