Merge pull request 'vctx: set VAULT_FORMAT from the vault command' (#3) from benvin/vctx-format into main

Reviewed-on: #3

docs/vctx.md

@@ -8,7 +8,7 @@ invocation only, and execs `vault` with the remaining arguments.
 ## Synopsis
 
 ```
-vctx --context <context> <any vault args...>
+vctx --context <context> [--format <fmt>] <any vault args...>
 vctx version
 ```
 
@@ -26,17 +26,34 @@ vctx --context sydney kv put kv/foo/bar secret=baz
    - `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.
 
-The ambient `VAULT_ADDR` / `VAULT_TOKEN` in your shell are ignored for the call
+The ambient `VAULT_ADDR` / `VAULT_TOKEN` / `VAULT_NAMESPACE` in your shell are ignored for the call
 — `vctx` always targets the chosen context.
 
-## The `--context` flag
+## Output format
 
-`--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`
+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:
 
 ```bash