123 lines
4.5 KiB
Markdown
123 lines
4.5 KiB
Markdown
# 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`](vcm.md)),
|
|
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).
|
|
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](#output-format))
|
|
4. `exec`s 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](#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, SIGINT/SIGTERM are forwarded, 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`) 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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).
|