vault-tools/AGENTS.md

AGENTS.md

Project Overview

vault-tools is a Go monorepo of small CLIs for managing Vault tokens across multiple vault instances ("contexts"):

• vctl — logs in to / renews Vault tokens per context (login, renew, list), with --all, --method and --user flags. Caches each token under ~/.cache/vault/<context> as JSON (token + accessor + policies + TTL/expiry).
• vctx — thin wrapper around the real vault CLI: vctx --context <ctx> <vault args...> resolves the context, sets VAULT_ADDR/VAULT_TOKEN/VAULT_NAMESPACE, and execs vault.

Both tools share the shared/ package (config parsing, token cache, Vault HTTP client) and read the SAME config file (~/.config/vault/vctl.yaml or config.yaml) and token cache so one ~/.config/vault/ configures everything.

Structure

shared/            # config.go, cache.go, vault.go (+ *_test.go)
vctl/main.go       # vctl CLI (module main package)
vctx/main.go       # vctx CLI (module main package)
docs/vctl.md       # per-command docs
docs/vctx.md
go.mod             # module git.unkin.net/unkin/vault-tools
Makefile           # build / test / lint / completions / rpm / version-bump
packaging/nfpm.yaml# nfpm spec (envsubst-templated) for the RPM (both binaries)
scripts/build-rpm.sh
.woodpecker/       # CI: build, test, pre-commit (PR) + release (tag)
dist/              # build output: binaries, completions, RPM (not committed)

Each tool is a separate main package under its own folder, so make build builds each with its own -o (a single go build ./... can't emit multiple mains to one file).

Build / test

make build          # -> dist/vctl, dist/vctx
make test           # go test -race ./...
make completions    # -> dist/completions/{vctl,vctx}.{bash,fish}, _{vctl,vctx}
make rpm            # build + nfpm RPM (bundles completions)
go build ./... && go test ./...

Conventions

• Config/cache dirs honour $XDG_CONFIG_HOME / $XDG_CACHE_HOME.
• Context names may contain slashes (staging/sydney) and nest in the cache; names are validated to prevent path traversal (see shared/cache.go).
• Token files are 0600, their parent dirs 0700; writes are atomic (temp file + rename).
• shared/vault.go is a small hand-rolled Vault HTTP client (no hashicorp/vault/api dependency) — only cobra, yaml.v3, x/term.

Releasing

Releases run in Woodpecker on v* tags. make patch|minor|major tags + pushes. The release pipeline cross-compiles both binaries, builds an RPM (with completions), PUTs it to the artifactapi rpm-internal yum repo, and cuts a Gitea release. Every pipeline step sets k8s resources and serviceAccountName: default; the release step uses the RELEASER_TOKEN Woodpecker secret.