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>] <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).
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.

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.

Flags

--context and --format 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).