| name | aqua-tooling |
| description | How to manage dev tools with aqua (aquaproj) in this repo — adding tools, updating versions, and keeping aqua-checksums.json in sync. Use whenever aqua.yaml or aqua-checksums.json is touched, when the user asks to add/update/pin a CLI tool (node, gh, pnpm, etc.), when tool versions drift between local and CI, or when aqua install fails with a checksum/policy error. Version bumps are NOT complete until checksums are regenerated. |
aqua Tooling Workflow
This repo pins all dev tools (node, gh, pnpm) with aqua
so local dev and CI resolve identical versions. Facts below were verified against
the official docs (2026-07-09); source URLs at the bottom.
Repo-specific invariants
aqua.yaml at repo root is the source of truth. CI installs tools from it via
aquaproj/aqua-installer, cached on hashFiles('aqua.yaml').- Checksum verification is enforced (
checksum.enabled: true +
require_checksum: true), so every version bump MUST regenerate
aqua-checksums.json — otherwise aqua i fails for everyone, including CI.
nodejs/node version must equal .nvmrc (user shell resolves node via nvm,
non-interactive shells via aqua). Keep them in sync in the same commit.pnpm/pnpm version must equal packageManager in root package.json.- The standard registry
ref carries a # renovate: depName=aquaproj/aqua-registry
marker — keep the comment when editing the line.
Workflow: update tool versions
- Find latest versions. Either run
aqua update (aqua up) which rewrites
aqua.yaml in place (updates BOTH registry refs and package versions; it
edits config only, installs nothing), or look up tags manually
(gh api repos/<owner>/<repo>/releases/latest --jq .tag_name) and edit
aqua.yaml. To update a single tool: aqua update gh.
- Sync the mirrors:
.nvmrc for node, packageManager for pnpm (see above).
- Regenerate checksums:
aqua -c aqua.yaml update-checksum -prune
Always pass -c aqua.yaml. Without it, aqua walks parent directories and
processes every config it finds on the way to / — inside a
.claude/worktrees/* worktree this writes a stray aqua-checksums.json into
the main repo checkout. (-prune drops entries for versions no longer in
aqua.yaml.)
- Verify and install:
aqua -c aqua.yaml i -l must succeed (it verifies
checksums), then spot-check node --version etc.
- Run the quality gates (
pnpm install --frozen-lockfile && pnpm typecheck && pnpm lint && pnpm test) before committing. Commit aqua.yaml,
aqua-checksums.json, and the synced files together.
Notes on aqua update behavior: packages with an explicit version: field or
update: enabled: false are skipped; -r updates only registries, -p only
packages; it only touches the first config found (another reason to stay at the
repo root or use -c).
Workflow: add a new tool
aqua g -i <owner>/<repo> inserts the package (latest version, pinned) into
aqua.yaml. Without args it opens an interactive fuzzy finder; add -s to
pick the version. Only packages in the standard registry install without
extra setup — aqua v2 allows ONLY the standard registry unless a policy file
(aqua-policy.yaml + aqua policy allow) permits others.- Regenerate checksums and install (steps 3–5 above).
Checksum semantics (why the file is required)
enabled: true turns verification on; require_checksum: true makes a
missing entry a hard failure instead of best-effort (both default to false).aqua update-checksum (aqua upc) creates/updates aqua-checksums.json for
all packages, all platforms, plus the registry itself. Checksums come from the
tool's published checksum files when available (gh's checksums.txt, node's
SHASUMS), otherwise from hashing the downloaded asset.aqua i also appends missing checksums for the current platform as it
installs, but only upc covers all platforms — CI runs linux, so a
darwin-only update is not enough. Always run upc.- If
aqua-checksums.json ever gets noisy, checksum.supported_envs
(e.g. [darwin, linux]) limits recorded platforms.
CI / Renovate reference
Command quick reference
| Command | Effect |
|---|
aqua i -l | Create shim links only; binaries download lazily on first run |
aqua i | Install everything in the config now |
aqua i -a | Also install global-config (AQUA_GLOBAL_CONFIG) packages |
aqua g -i <pkg> | Search registry and insert pinned package into aqua.yaml |
aqua up / aqua update <cmd> | Bump versions in aqua.yaml (no install) |
aqua upc -prune | Regenerate aqua-checksums.json, dropping stale entries |
aqua which <cmd> | Absolute path of the resolved binary (-v for version) |
aqua list -i | List installed packages |
Config discovery: -c/AQUA_CONFIG wins; otherwise aqua searches
.?aqua.ya?ml and .?aqua/aqua.ya?ml from cwd upward to filesystem root and
reads every match it finds — the root cause of the worktree gotcha above.
Never use floating versions: registry ref must be a tag or commit (never a
branch), and packages must be pinned — "latest" breaks reproducibility and CI
without any code change (official docs' core rationale).
Sources
