# 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`](docs/vctl.md) | Log in to / renew Vault tokens per context and cache them on disk.    |
| [`vctx`](docs/vctx.md) | 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/`](docs/) for full details.

## Quick start

```bash
# 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](docs/vctl.md#configuration) 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

```bash
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:

```bash
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.