What Dependencies Does Aqua Manage? A Complete Guide to CLI Package Types

Aqua manages CLI tool dependencies distributed as GitHub releases, archives, content files, HTTP downloads, Go modules, and Rust crates, installing them as versioned binaries without requiring compilation.

Aqua is a declarative version manager for command-line tools developed in the aquaproj/aqua repository. Unlike traditional package managers that build from source, Aqua downloads pre-built binaries or archives defined in YAML configuration files, supporting seven distinct dependency types defined in the core configuration code.

The Seven Dependency Types Defined in Aqua's Core

Aqua categorizes dependencies using the PkgInfoType* constants declared in pkg/config/package.go. Each type determines how the tool is fetched, resolved, and installed on your system.

GitHub Release Binaries

The github_release type downloads assets attached to GitHub releases. This is the most common pattern for modern CLI tools.

In pkg/config/package.go line 315, this type is defined for packages like suzuki-shunsuke/tfcmt. The GitHubReleaseVersionGetter in pkg/versiongetter/github_release.go (line 14) handles version resolution by querying the GitHub API for release tags and asset URLs.

GitHub Content Files

The github_content type fetches individual files directly from a repository. Use this for single-script tools or configuration files hosted on GitHub.

Defined at line 317 in pkg/config/package.go, this type bypasses release assets and downloads raw content from specific repository paths.

GitHub Archives

The github_archive type downloads entire repository archives as tar or zip files. This suits tools that bundle multiple scripts or require the full source tree to function.

Found at line 319 in pkg/config/package.go, this dependency type retrieves source archives without cloning the repository.

HTTP Downloads

The http type supports arbitrary URLs for tools hosted outside GitHub. This provides flexibility for proprietary tools or mirrors.

Defined at line 321 in pkg/config/package.go, the HTTPDownloader in pkg/download/http.go handles fetching these resources securely with checksum verification support.

Go Install Packages

The go_install type installs Go-based CLI tools using go install with explicit module paths and versions.

Located at line 324 in pkg/config/package.go, this type delegates to the Go toolchain rather than downloading pre-built binaries, ensuring compatibility with your Go environment.

Go Build From Source

The go_build type compiles Go binaries from source using custom build instructions. Unlike go_install, this allows custom build flags or specific entry points.

Defined at line 326 in pkg/config/package.go, this type requires a build command specification in your Aqua configuration.

Rust Crates

The cargo type installs Rust binaries from crates.io using cargo install. This manages Rust-based CLI tools like ripgrep or bat with specific version pinning.

Found at line 328 in pkg/config/package.go, this dependency type integrates with the Cargo ecosystem for Rust package management.

How Aqua Resolves and Downloads Dependencies

Aqua separates version resolution from download logic across two subsystems.

The version-getter subsystem (pkg/versiongetter/*.go) resolves the latest version or validates pinned versions. For GitHub-based types, it queries the GitHub API; for Go and Rust types, it queries module registries or crates.io.

The download subsystem (pkg/download/*.go) handles the actual retrieval. The HTTPDownloader manages direct downloads, while specialized getters handle GitHub assets. Both subsystems support checksum verification to ensure binary integrity.

Configuring Dependencies in aqua.yaml

Define your dependencies in aqua.yaml by specifying the type and required parameters for each package:

packages:
  # GitHub Release – binary asset on a GitHub release

  - name: tfcmt
    type: github_release
    repo: suzuki-shunsuke/tfcmt
    asset: tfcmt_{{.Version}}_{{.OS}}_{{.Arch}}.tar.gz

  # GitHub Content – a single file in a repo

  - name: myscript
    type: github_content
    repo: example/myscripts
    path: bin/myscript.sh

  # GitHub Archive – whole repo archive

  - name: tfenv
    type: github_archive
    repo: tfutils/tfenv

  # HTTP – direct download URL

  - name: jq
    type: http
    url: https://github.com/stedolan/jq/releases/download/jq-{{.Version}}/jq-linux64

  # Go Install – use `go install` (module@version)

  - name: go-task
    type: go_install
    module: go-task/task

  # Go Build – build from source with custom build command

  - name: kustomize
    type: go_build
    repo: kubernetes-sigs/kustomize
    build: go build -o kustomize ./cmd/kustomize

  # Cargo – install Rust binary from crates.io

  - name: ripgrep
    type: cargo
    crate: ripgrep

Leveraging the Standard Registry

Aqua provides a Standard Registry (the aqua-registry repository) containing thousands of pre-configured packages. Instead of writing custom definitions, reference registry packages directly:

# Install the latest version of Terraform (provided by the standard registry)

aqua i terraform

The registry entry for Terraform uses the github_release type pointing to HashiCorp's GitHub releases, as defined in the registry's pkgs/hashicorp/terraform/registry.yaml.

For private tools, extend the standard registry with custom entries:

registries:
  - type: github_content
    repo: myorg/private-registry
    path: registry.yaml
    ref: v1.2.3

packages:
  - name: my-tool
    type: github_release
    repo: myorg/my-tool
    version: 2.0.0

Summary

• Aqua manages seven distinct dependency types defined in pkg/config/package.go: GitHub releases, content files, archives, HTTP downloads, Go installs, Go builds, and Cargo crates.
• The version-getter and download subsystems handle resolution and fetching separately, ensuring checksum verification and security.
• Pre-built binaries are preferred over compilation, though Go and Rust toolchains are supported when necessary.
• The Standard Registry provides thousands of ready-to-use package definitions, while private registries support internal tooling.

Frequently Asked Questions

Does Aqua manage library dependencies or only CLI tools?

Aqua exclusively manages CLI tool binaries and executables. It does not handle language-specific library dependencies like npm packages, Python wheels, or Go modules imported by your application code. Aqua focuses on the installation and versioning of command-line interfaces rather than build-time dependencies.

How does Aqua handle private GitHub repositories?

Aqua supports private repositories through the github_release, github_content, and github_archive types using your configured GitHub access tokens. Set the AQUA_GITHUB_TOKEN environment variable or configure GitHub CLI authentication. The GitHubReleaseVersionGetter in pkg/versiongetter/github_release.go respects these credentials when resolving versions and downloading assets.

What is the difference between go_install and go_build in Aqua?

The go_install type delegates to go install to fetch and compile Go modules directly from version control, ideal for tools distributed as standard Go modules. The go_build type clones the repository locally and executes a custom build command (specified in the build field), necessary when tools require specific build flags, ldflags, or non-standard entry points. Use go_install for simplicity; use go_build when you need compilation customization.

Can Aqua manage dependencies from GitLab or other Git hosts?

Currently, Aqua's native dependency types focus on GitHub, HTTP, and language-specific registries (crates.io, Go modules). For GitLab or Bitbucket, use the http type with direct download URLs pointing to release assets, or configure a custom registry that references these URLs. The http type in pkg/config/package.go line 321 supports any host accessible via HTTP or HTTPS.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}