unkinben
123faf8bbf
Introduces the vault-tools monorepo: two Go CLIs that share a config file (~/.config/vault) and token cache (~/.cache/vault) for working with multiple Vault instances (contexts). - add shared/ library: config parsing (vctl.yaml/config.yaml, per-context overrides, slash contexts), token cache (0600/0700, atomic writes, path- traversal guards), and a small hand-rolled Vault HTTP client (login/renew) - add vctl: login/renew (single or --all), list, --method/--user overrides, no-echo password/token prompts, dynamic context completion - add vctx: resolve a context, set VAULT_ADDR/VAULT_TOKEN/VAULT_NAMESPACE and exec the vault CLI, passing remaining args through untouched - add unit tests across shared/, vctl and vctx command layers (config resolution, cache paths, vault client, --all iteration + error aggregation, vctx arg pass-through and env construction via fakeable exec/prompt seams) - add Makefile (build/test/completions/rpm, patch|minor|major version bumps), nfpm RPM packaging bundling bash/zsh/fish completions for both binaries - add Woodpecker pipelines: build/test/pre-commit on PRs, and a tag release that cross-compiles, builds+uploads the RPM to artifactapi, and cuts a Gitea release (serviceAccountName default, k8s resources on every step) - add README, per-command docs (docs/vctl.md, docs/vctx.md), AGENTS.md and an example config Claude-Session: https://claude.ai/code/session_015ur3i7D2azsMAWTSVABApv
3.5 KiB
vault-tools
A Go monorepo of small CLI tools for working with multiple Vault instances
("contexts"). Both tools share a single config file (~/.config/vault/) and
token cache (~/.cache/vault/), so once a context is configured every tool
knows about it.
| Tool | Purpose |
|---|---|
vctl |
Log in to / renew Vault tokens per context and cache them on disk. |
vctx |
Run the real vault CLI against a named context (sets VAULT_ADDR/VAULT_TOKEN/VAULT_NAMESPACE, then execs vault). |
See the per-command docs in docs/ for full details.
Quick start
# 1. Configure your vaults
mkdir -p ~/.config/vault
cat > ~/.config/vault/vctl.yaml <<'YAML'
defaults:
method: ldap
user: ben
contexts:
sydney:
address: https://vault.syd1.au.unkin.net
staging/sydney:
address: https://vault-staging.syd1.au.unkin.net
namespace: staging
YAML
# 2. Log in (prompts for password), caches a token under ~/.cache/vault/
vctl login sydney
vctl login --all # or log in to every context at once
# 3. Use the vault CLI against a context
vctx --context sydney kv put kv/foo/bar secret=baz
vctx --context staging/sydney kv list kv/
# 4. Keep tokens fresh
vctl renew --all
# See what's configured and which tokens are still valid
vctl list
Configuration
Both tools read the first of ~/.config/vault/vctl.yaml or
~/.config/vault/config.yaml that exists ($XDG_CONFIG_HOME honoured). The
file maps context names to a vault address plus optional per-context overrides
(method, user, namespace, path) with file-level defaults. Context
names may contain slashes, which nest on disk in the token cache. See
docs/vctl.md for the full schema and resolution
rules.
Tokens are cached under ~/.cache/vault/<context> ($XDG_CACHE_HOME honoured)
as JSON with restrictive permissions (files 0600, dirs 0700), storing the
token plus its accessor, policies, TTL/expiry and renewable flag.
Layout
shared/ # config parsing, token cache, Vault HTTP client (shared lib + tests)
vctl/ # vctl CLI (main package)
vctx/ # vctx CLI (main package)
docs/ # per-command documentation
packaging/nfpm.yaml# nfpm spec (envsubst-templated) for the RPM (both binaries + completions)
scripts/build-rpm.sh
.woodpecker/ # CI: build, test, pre-commit (PR) + release (tag)
Makefile # build / test / completions / rpm / version-bump targets
Building
make build # build vctl + vctx into dist/
make test # go test -race ./...
make completions # generate bash/zsh/fish completions into dist/completions/
make rpm # build + package an RPM (needs nfpm)
Releasing
Releases run in Woodpecker on a v* tag. Bump and tag with:
make patch # or: make minor / make major
which creates the next semver tag and pushes it. The release pipeline then
tests, cross-compiles both binaries (linux/darwin × amd64/arm64), builds an RPM
(bundling shell completions), PUTs the RPM to the artifactapi local rpm-internal
yum repo, and cuts a Gitea release with the binaries + checksums attached.
Installation
Install the RPM from the internal yum repo (ships both binaries plus bash/zsh/fish completions), or grab a prebuilt binary from the Gitea release assets.