# 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 [`vctl`](vctl.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> <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/vault/vctl.yaml` (or
   `config.yaml`) — the exact file `vctl` uses.
2. Loads the cached token from `~/.cache/vault/sydney` (errors with a hint to
   run `vctl 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. `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.

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:

```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 (`vctl 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).