vault-tools/docs/vctx.md

vctx

vctx is a thin, context-aware wrapper around the real vault CLI. It resolves a context (using the same config file and token cache as vcm), sets VAULT_ADDR, VAULT_TOKEN and VAULT_NAMESPACE for that single invocation only, and execs vault with the remaining arguments.

Synopsis

vctx --context <context> [--format <fmt>] [--color auto|always|never] <any vault args...>
vctx version

How it works

vctx --context sydney kv put kv/foo/bar secret=baz

1. Resolves the sydney context from ~/.config/vcm/config.yaml — the exact file vcm uses.
2. Loads the cached token from ~/.cache/vcm/sydney (errors with a hint to run vcm login sydney if none exists or it is locked after a reboot).
3. Sets, for this process only:
   • VAULT_ADDR = the context's address
   • VAULT_TOKEN = the cached token
   • VAULT_NAMESPACE = the context's namespace (only if non-empty; falls back to the namespace recorded in the cached token)
   • VAULT_FORMAT = --format if given, else picked from the command (see Output format)
4. execs the vault binary (found on PATH) with everything after the context. Because it replaces the process, vault's exit status, signals and TTY behaviour pass straight through (json/yaml output on a terminal is instead run as a child and colourised; see Colour).

The ambient VAULT_ADDR / VAULT_TOKEN / VAULT_NAMESPACE in your shell are ignored for the call — vctx always targets the chosen context.

Output format

Without --format, vctx sets VAULT_FORMAT from the vault command:

Command	VAULT_FORMAT
kv list ...	table
kv get ...	yaml
any path containing /creds/ (read/write)	yaml
anything else	unset (vault default)

It is left alone when VAULT_FORMAT is already set in the environment or the vault args include -format or -field. --format (table, json, yaml, pretty; raw for vault read only) always sets it, overriding the environment.

Colour

When the effective format is json or yaml (from the table above, --format, a -format vault arg, or VAULT_FORMAT), vctx colourises vault's output like jq/yq. To do so it runs vault as a child instead of exec'ing it: stdin and stderr pass straight through, stdout is buffered and re-emitted coloured, SIGTERM/SIGHUP are forwarded (SIGINT already reaches vault from the terminal), and vault's exit code is returned (128+n if killed by signal n).

--color controls this:

Value	Behaviour
auto	colour only when stdout is a terminal, NO_COLOR is unset/empty and TERM is not dumb (default)
always	always colour
never	never colour

Without colour (piped output, NO_COLOR, table/raw/pretty formats) vctx execs vault exactly as before, so scripts see unchanged output. Streaming or interactive commands (monitor, debug, events, ssh, agent, proxy, server, login, operator, and write/patch, which may prompt for MFA) are always exec'd and never coloured. JQ_COLORS overrides the JSON palette as in jq.

Flags

--context, --format and --color are the only flags vctx consumes; they must come before the vault command. Everything from the first non-flag argument onward is handed to vault untouched, so vault's own flags work normally:

vctx --context sydney kv get -field=password secret/db
vctx --context staging/sydney token lookup
vctx --context sydney -help          # 'vctx --context X' then vault sees -help

Context names support slashes (e.g. staging/sydney), matching the config and the on-disk token cache.

Examples

# Write a secret to the sydney vault
vctx --context sydney kv put kv/foo/bar secret=baz

# Read a single field
vctx --context sydney kv get -field=secret kv/foo/bar

# Operate against a namespaced, slash-named context
vctx --context staging/sydney kv list kv/

# Inspect the token vctx would use
vctx --context sydney token lookup

Requirements

• The vault CLI must be installed and on PATH.
• A token must already be cached for the context (vcm login <context>).

Shell completion

vctx completion bash > /etc/bash_completion.d/vctx
vctx completion zsh  > ~/.zsh/completions/_vctx

The --context value completes dynamically from the configured context names, so vctx --context <TAB> lists your vaults (the RPM installs these completions automatically).