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.