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

> Discover the diverse dependencies aqua manages including GitHub releases archives HTTP downloads Go modules and Rust crates Install versioned binaries without compilation.

- Repository: [aquaproj/aqua](https://github.com/aquaproj/aqua)
- Tags: deep-dive
- Published: 2026-02-25

---

**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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/pkg/config/package.go) line 315, this type is defined for packages like `suzuki-shunsuke/tfcmt`. The `GitHubReleaseVersionGetter` in [`pkg/versiongetter/github_release.go`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/pkg/config/package.go), the `HTTPDownloader` in [`pkg/download/http.go`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) by specifying the type and required parameters for each package:

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

```bash

# 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`](https://github.com/aquaproj/aqua/blob/main/pkgs/hashicorp/terraform/registry.yaml).

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

```yaml
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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/pkg/config/package.go) line 321 supports any host accessible via HTTP or HTTPS.