DOCSEARCHbyAlgolia
Submit Docs

aqua CLI Reference

website·Indexed 30 days ago

https://aquaproj.github.io/

Documentation for aqua, a CLI tool for managing package installations. Includes reference guides for registry configuration (overrides, version filters, and SLSA provenance), security features like GitHub Artifact Attestations and policy-as-code, and upgrade guides for v2.

Tokens
41.8K
Snippets
253
Records
346
Agent score
74%

What's inside aqua

  1. Overview of aqua CLI Version Manager

    aqua is a declarative CLI version manager written in Go. It allows developers to manage tool versions using a YAML configuration file (aqua.yaml), ensuring that all team members and CI environments use the exact same tool versions. Unlike general package managers (e.g., Homebrew), aqua supports switching tool versions per project and prohibits the installation of 'latest' versions to prevent unexpected CI breakages.

  2. Overview of aqua CLI

    aqua is a CLI tool used to install other CLI tools using a declarative YAML configuration file. It manages tool versions and installations in a centralized directory defined by ${AQUA_ROOT_DIR}.

  3. Overview of aqua Policy-as-Code

    Policy is a security feature in aqua (v2.3.0+) used to restrict package installation and execution to prevent malicious tools from being run. By default, aqua only allows the Standard Registry. If you use non-standard or local registries, you must create a Policy file to explicitly allow them.

  4. Understand aqua policy types

    aqua supports two types of policies:

    1. Git Repository root's policy file (Recommended)
    2. AQUA_POLICY_CONFIG environment variable

    The Git Repository root policy file is the preferred method as it addresses limitations found in the AQUA_POLICY_CONFIG approach.

  5. Debug aqua execution with AQUA_LOG_LEVEL

    When aqua does not work as expected, use the AQUA_LOG_LEVEL environment variable set to debug to get detailed logs about package installation, permission checks, and execution paths.
    AQUA_LOG_LEVEL=debug kind --help

  6. Understand and use aqua Lazy Install

    Lazy Install is a feature in aqua that automatically installs a tool when it is executed if the specified version is not yet installed. This allows developers to avoid running aqua i manually to update or install packages and ensures that the correct tool version is executed on demand.
    $ gh version
INFO[0000] download and unarchive the package aqua_version=1.19.2 package_name=cli/cli package_version=v2.1.0 program=aqua registry=standard
gh version 2.1.0 (2021-10-14)

  7. Distinguish artifacts using runtime variants (libc)

    For aqua >= v2.58.0, the variants field allows matching artifacts that share the same OS and architecture but differ by another axis, such as the C library (libc). An override matches only when every variant's value equals the value detected by aqua at runtime.

    Currently supported variant keys:

    • libc: Values can be musl or glibc. On Linux, aqua detects this via the presence of /lib/ld-musl-*.so.1 or /lib/libc.musl-*.so.1, or by checking ldd --version output.

    You can manually override the detected libc using the AQUA_LIBC environment variable (e.g., AQUA_LIBC=musl).

    overrides:
  - goos: linux
    goarch: amd64
    variants:
      - key: libc
        value: musl
    asset: foo-{{.OS}}-{{.Arch}}-musl.{{.Format}}

  - goos: linux
    goarch: amd64
    variants:
      - key: libc
        value: glibc
    asset: foo-{{.OS}}-{{.Arch}}-glibc.{{.Format}}

  8. Manage experimental features in aqua

    Starting with aqua v1.6.0, aqua supports experimental features. These features are disabled by default and must be enabled via environment variables. Note that experimental features are an exception to semantic versioning; they may be modified, aborted, or enabled by default in minor or patch updates without a major version bump.

  10. Update aqua-checksums.json using update-checksum-action

    The update-checksum-action is a GitHub Action that checks if aqua-checksums.json is up-to-date. If it is not, the action updates the file and pushes a commit to the repository. Note that for many use cases, autofix.ci or Securefix Action are recommended alternatives to this action.

  11. Use rosetta2 to support amd64 binaries on Apple Silicon

    The rosetta2 field allows a package to automatically use the amd64 architecture when the system is running macOS (GOOS=darwin) on Apple Silicon (GOARCH=arm64). When rosetta2 is set to true, the template variable {{.Arch}} is interpreted as amd64 for these specific systems, eliminating the need for manual if conditions in the asset string. By default, rosetta2 is false.
    rosetta2: true
asset: 'argo-{{.OS}}-{{.Arch}}.gz'