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> <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)
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 in your shell are ignored for the call — vctx always targets the chosen context.

The --context flag

--context is the only flag vctx consumes; it 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).