aqua Documentation

aqua is a declarative CLI version manager written in Go. It allows developers to manage tool versions on a per-project basis, ensuring consistency across teams and CI environments.

Key features include:

• Per-project version switching: Define specific tool versions for each project.
• Unified installation: Standardize how tools are installed for teams and CI.
• Continuous updates: Integrates with Renovate for automated dependency updates.
• Lazy Install: Tools are installed only when needed.
• Registry-based ecosystem: Uses registries to manage tool availability.
• Security: Designed with a focus on secure tool management.

aqua is a declarative CLI Version Manager written in Go. It allows you to manage tool versions using a YAML configuration file (typically aqua.yaml). Unlike standard package managers (e.g., Homebrew), aqua enables you to specify and switch tool versions on a per-project basis, ensuring consistency across local development environments and CI/CD pipelines.

registries:
- type: standard
  ref: v4.155.1 # renovate: depName=aquaproj/aqua-registry

packages:
- name: cli/cli@v2.2.0
- name: junegunn/fzf@0.28.0

The aqua ecosystem consists of several tools designed for CLI version management, registry maintenance, and CI/CD integration:

• aqua: The main CLI Version Manager.
• aqua-registry: The standard registry for aqua.
• aqua-installer: A shell script and GitHub Action used to install aqua.
• circleci-orb-aqua: A CircleCI Orb for installing aqua in CircleCI environments.
• aqua-renovate-config: A Renovate Config Preset to automate updates for aqua, aqua-installer, packages, and registries.
• devcontainer-features: Dev Container Features for integrating aqua into development containers.

What is aqua-proxy?

aqua-proxy is the internal CLI tool for aqua. Its primary responsibility is to dynamically decide the version of aqua and the packages managed by aqua based on the aqua configuration file at the moment a package is executed.

Installation

You do not need to install aqua-proxy explicitly. It is automatically installed to $AQUA_ROOT_DIR/bin/aqua-proxy whenever you run:

• aqua install
• aqua exec

Usage Note

aqua-proxy is designed specifically for aqua and is not intended for use as a standalone tool. It maintains a minimal feature set and is kept stable to ensure consistent behavior for aqua users.

aqua provides several advanced security features and integrations to ensure the integrity and provenance of installed tools:

• Checksum Verification: Verifies the integrity of tools using checksums.
• Policy as Code: Allows defining security policies for tool installation.
• ghtkn integration: Integration with ghtkn for secure tool management.
• Cosign and SLSA Provenance: Supports verifying software supply chain provenance using Cosign and SLSA standards.
• Minisign: Supports tool verification using Minisign.
• GitHub Artifact Attestations: Utilizes GitHub's artifact attestation feature for provenance.
• Keyring Integration: Allows managing GitHub access tokens securely using a system keyring.

Policy is a security feature in aqua >= v2.3.0 designed to restrict package installation and execution, preventing malicious tools from being run via unauthorized registries.

By default, aqua only allows the Standard Registry, which protects users from malicious tools in non-standard registries. If your workflow requires using non-standard registries (e.g., a local registry or a private GitHub registry), you must define an aqua-policy.yaml file to explicitly allow them.

Starting from aqua v2.5.0, on Linux and macOS, aqua-proxy and aqua use the execve(2) system call to execute commands instead of spawning them as subprocesses.

Benefits:

• Prevents the creation of extra subprocesses in the process tree.
• Reduces overhead and potential instability caused by the aqua-proxy -> aqua -> x chain.

Limitations:

• Windows is not supported because Windows does not support execve(2). On Windows, the old subprocess behavior is used.

$ nvim # nvim is managed by aqua
$ pstree -s nvim

# New behavior (v2.5.0+ on Linux/macOS):
     \-+= 82315 shunsukesuzuki -zsh
       \-+= 82630 shunsukesuzuki nvim

When a package provides both musl and glibc binaries, the choice depends on whether the musl build is static or dynamic:

1. If the musl build is static: Always use the musl build. It is simpler and avoids glibc version compatibility issues.
2. If the musl build is dynamic: Use the glibc build by default. Use the musl build via variants only in environments where the musl build is required (e.g., Alpine Linux).

You can check if a binary is dynamically linked using file, ldd, readelf -d, or objdump -p | grep NEEDED.

By design, aqua's installation process is limited to two steps: downloading a tool and unarchiving it into $AQUA_ROOT_DIR.

aqua does not support running external commands to install tools. This restriction is a deliberate design choice to ensure the tool remains simple, secure, dependency-free, and easy to maintain/troubleshoot. aqua will not change files outside of its install directory and does not require external dependencies to function.

While most tools must follow the download-and-unarchive pattern, there are specific exceptions that support more complex installation methods, including:

• cosign and slsa-verifier
• minisign
• gh (GitHub artifact attestations)
• go (via go install package)
• cargo (via cargo package)