Skip to content

Authentication

The CLI supports four ways to log in. Browser login is the default for interactive use. API access tokens are the primary mechanism for headless and CI/CD use.

Each successful login is stored under your Vault username. Use vault switch to change the active Vault, or vault user switch to change which user is current.

Running vault login prompts for your Vault username, then opens login.veevavault.com in a browser.

vault login

If you have access to more than one Vault, the CLI shows a picker listing Vault names. If you have access to only one Vault, the CLI selects it automatically. Pass --dns to target a specific Vault and skip the picker:

vault login --dns myorg.veevavault.com

To use an API Access Token, pass --access-token and --dns for the Vault. The CLI prompts for the token. The CLI never accepts a secret as a flag value.

vault login --dns myorg.veevavault.com --access-token

Log in with an existing Vault API session ID with --session-id. You must also pass --dns. The CLI prompts for the session ID.

vault login --dns myorg.veevavault.com --session-id

Basic authentication uses your Vault username and password. You must also pass --dns and --username. The CLI prompts for the password.

vault login --dns myorg.veevavault.com --username user@example.com --password

In non-interactive environments, authenticate first with vault login, piping the access token via stdin. Subsequent commands use the stored login. To skip confirmation prompts, pass --yes to any command that would otherwise prompt for confirmation.

echo "$VAULT_TOKEN" | vault login --dns myorg.veevavault.com --access-token
vault config pull
vault config push --yes

Every login has a scope. By default, a login is kept in the current shell only, meaning the terminal tab or window you ran vault login in, including subshells and scripts started from it. Other shells on the same computer see their own set of logins.

Pass --scope global to save a login for every shell on this computer:

vault login --dns myorg.veevavault.com --scope global

Because a global login affects other shells, scripts, and agents on the machine, the CLI confirms it first when stdin is a terminal:

This login will be saved for every shell on this computer, including scripts and agents started from any of them.
Save it for every shell? (y/N)

The prompt defaults to no. Answering no, pressing Esc, or pressing Ctrl+C cancels without opening a browser, reading a secret, or sending anything to Vault. The CLI prints Canceled; nothing was saved. and exits 0.

In a non-interactive shell, a --scope global login without --yes is rejected before any browser or network activity:

a global login is saved for every shell on this computer; add -y to confirm

Pass --yes (or -y) to confirm non-interactively:

echo "$VAULT_TOKEN" | vault login --dns myorg.veevavault.com --access-token --scope global --yes

A shell-scope login of a username already logged in at global scope adds a separate entry. The global entry is left unchanged. The reverse also holds. A global-scope login of a username already logged in at shell scope adds a separate entry. The shell-scope entry is left unchanged.

The CLI confirms which user and Vault a command will act on before sending any request, the first time you run one of the following in a new shell:

  • vault api
  • vault query
  • vault mdl
  • vault config pull
  • vault config push
  • vault config package create
  • vault config package deploy

Commands outside this list, such as vault status, vault list, and vault user list, do not go through the gate. This confirmation protects against running a destructive command against the wrong Vault when a shell inherits a login.

If no login exists for any user at any scope when a gated command runs, the CLI exits 1 with not logged in; run 'vault login' first instead of showing the confirmation prompt.

In an interactive terminal, the CLI prints the pending user and Vault and prompts for a choice:

This shell hasn't confirmed which user and vault to use.
  User:  user@example.com (global scope)
  Vault: My Vault
Use this user and vault? [Confirm / Switch user / Switch vault / Cancel]

The four choices behave as follows:

  • Confirm commits the shell to that user and Vault for subsequent commands and runs the current command.
  • Switch user shows the same user picker as vault user switch and re-asks after you choose. If you cancel the picker, the CLI re-shows the original prompt unchanged.
  • Switch vault shows the same Vault picker as vault switch and re-asks. If you cancel the picker, the CLI re-shows the original prompt unchanged.
  • Cancel, Esc, or Ctrl+C prints Canceled; nothing was run. and exits 0 without contacting Vault.

For an access-token login, which is tied to a single Vault, Switch vault is not offered. When the prompt is re-shown after Switch user, the choice set reflects the newly selected user. Switch vault reappears if the new user is not an access-token login.

In a non-interactive shell, when stdin is not a terminal, the CLI does not prompt. It exits 4 with a message that depends on the shell's state:

# A shell with a current user that hasn't been confirmed:
this shell hasn't confirmed which user and vault to use; run 'vault user switch <username>' in it to confirm '<username>' on '<dns>', or set VAULT_CLI_USER=<username> for one command

# A shell with no current user and no suggested user:
this shell hasn't confirmed which user to use; run 'vault user switch' in it to pick one, or set VAULT_CLI_USER=<username> for one command

# A context with no shell at all (cron, CI service, Windows shortcut launch):
no shell to confirm a user in; set VAULT_CLI_USER=<username> to name the user for this command

--yes does not bypass this confirmation. The gate determines which identity the command uses, not whether to skip an action prompt.

VAULT_CLI_USER for One-off Commands

Section link for VAULT_CLI_USER for One-off Commands

For CI/CD pipelines and scripts that need to name an identity explicitly, set VAULT_CLI_USER=<username> to run a gated command as that user, on that user's current Vault, without the confirmation prompt:

VAULT_CLI_USER=ci-agent@example.com vault config push --yes

VAULT_CLI_USER applies only to the command it is set for. It leaves this shell's current user, confirmation, and the suggested user unchanged. If the named user is not stored on the machine, the command errors with no stored user '<username>' (from VAULT_CLI_USER); run 'vault login' to add it and exits 1.

An empty or whitespace-only VAULT_CLI_USER is treated as unset, so the command runs through the gate as usual. VAULT_CLI_USER has no effect on commands that are not gated.

If VAULT_CLI_DNS and VAULT_CLI_SESSION_ID are both set, they authenticate the command directly and VAULT_CLI_USER is ignored.

If you are upgrading from an earlier CLI version, the CLI migrates your stored logins to the new format on first run. Logins stored using --session-id or --access-token without a recorded username are dropped silently during migration. Run vault login again for those Vaults after upgrading. Downgrading to an earlier CLI version is not supported.

See the vault login reference for the full login and logout reference.