Skip to main content

· 3 min read
Shunsuke Suzuki

In this post, I describe the feature introduced from aqua v1.7.0. From v1.7.0, aqua supports building tools with Go when they are installed.

For example, mitchellh/gox doesn't provide built binaries, so you have to build it yourself.

https://github.com/mitchellh/gox#installation

To install Gox, please use go get. We tag versions so feel free to checkout that tag and compile.

So it was difficult for aqua to support gox.

But from v1.7.0, aqua has introduced a new package type named go to support these tools. When packages of the type go are installed, GitHub Repository archives (tarball) are downloaded and unarchived, and binaries are built by go build command. To run go build, Go is required. In my understanding, we can run go build safely because any external malicious commands aren't run in go build.

Usage​

The usage of go type packages are exactly the same as other type packages.

e.g.

$ aqua init
$ aqua g -i mitchellh/gox
$ cat aqua.yaml
---
# aqua - Declarative CLI Version Manager
# https://aquaproj.github.io/
registries:
- type: standard
  ref: v2.19.0 # renovate: depName=aquaproj/aqua-registry
packages:
- name: mitchellh/gox@v1.0.1

$ aqua i
INFO[0000] create a symbolic link                        aqua_version=1.9.0 env=darwin/arm64 link_file=/Users/shunsukesuzuki/.local/share/aquaproj-aqua/bin/gox new=aqua-proxy package_name=mitchellh/gox package_version=v1.0.1 program=aqua registry=standard registry_ref=v2.19.0
INFO[0000] download and unarchive the package            aqua_version=1.9.0 env=darwin/arm64 package_name=mitchellh/gox package_version=v1.0.1 program=aqua registry=standard registry_ref=v2.19.0
INFO[0000] building Go tool                              aqua_version=1.9.0 env=darwin/arm64 exe_path=/Users/shunsukesuzuki/.local/share/aquaproj-aqua/pkgs/go/github.com/mitchellh/gox/v1.0.1/bin/gox file_name=gox go_build_dir=/Users/shunsukesuzuki/.local/share/aquaproj-aqua/pkgs/go/github.com/mitchellh/gox/v1.0.1/src/gox-1.0.1 go_src=. package_name=mitchellh/gox package_version=v1.0.1 program=aqua registry=standard registry_ref=v2.19.0
go: downloading github.com/hashicorp/go-version v1.0.0
go: downloading github.com/mitchellh/iochan v1.0.0

Please see the log of aqua i. You can confirm that gox is built.

Benefit​

  • Support installing tools that no binary is provided
  • Pin the tool version
  • Change the tool version per project
  • Update tools by Renovate

Specify a commit sha instead of a tag​

Some tools aren't tagged properly, or there is too much difference between the latest tag and the latest default branch. In that case, you can also specify a commit sha as a version instead of a tag.

e.g. aqua.yaml

registries:
- type: standard
  ref: v2.19.0
packages:
- name: mitchellh/gox
  version: 8c3b2b9e647dc52457d6ee7b5adcf97e2bafe131 # Specify commit sha

Can we specify latest like go install?​

As you know, go install supports specifying latest.

e.g.

$ go install github.com/google/wire/cmd/wire@latest

On the other hand, aqua doesn't support specifying latest because aqua is CLI Version Manager. You must specify the version strictly.

Example tools supported by package type go​

In the release of aqua-registry v2.19.0, aqua-registry has supported the following go type packages.

Conclusion​

In this post, I've described the feature introduced from aqua v1.7.0. From v1.7.0, aqua supports building tools with Go when they are installed. This feature is powerful and changes the management of Go tools that don't provide binaries.

Reference​

· 2 min read
Shunsuke Suzuki

Original Post: https://dev.to/suzukishunsuke/why-i-use-aqua-230

In this post, I describe why I use aqua.

Why I use aqua​

  • Align tool versions in team and CI
    • Solve the problem due to the difference of tool versions
  • Manage tools and their versions for projects as code declaratively, and provide an unified way to install tools
    • aqua supports changing tool versions per project
  • Stop developing shell scripts and GitHub Actions to install tools per tool and per project
  • Update tools with Renovate easily
  • Install tools hosted in private repositories

Why not asdf?​

asdf is used for the similar purpose, but I use aqua. Why?

  • Some tools don't have asdf plugins for them
  • Good Experience
    • You don't have to install plugins
    • Tools are installed automatically
    • Search tools by aqua g is useful
  • aqua doesn't force to use aqua in other projects and globally
  • Easy to support new tools
    • It is easier to contribute to aqua-registry than to develop asdf plugin
  • Easy to introduce aqua to teams and projects because aqua is easy and doesn't force to use aqua in other projects and globally
  • Easy to update tools with Renovate
  • aqua supports splitting configuration files, so it is easy to filter builds in CI by changed file paths

About the difference between aqua and asf, please see Compared with asdf too.

· 4 min read
Shunsuke Suzuki

Original Post: https://medium.com/@suzuki.shunsuke.1989/manage-cli-tool-version-with-aqua-cee38b2c4bf5

In this post, I introduce the CLI tool aqua, which manages CLI tool version with YAML.

When I write this post, the latest version of aqua is v0.8.0.

aqua is a single binary written in Go, so you can install it easily. Unlike other package managers such as Homebrew, aqua manages CLI tools with declarative YAML Configuration files.

Pin Tool Version​

aqua forces to pin tool version, which solves the problem due to the difference of tool version.

Auto update with Renovate​

With Renovate Preset Config for aqua, you can update tools continuously with Renovate.

Lazy Install​

When the tool is invoked, aqua installs the tool automatically. This feature ensures the executed tool version is exactly same as the configuration.

Change tool version easily​

By editing the tool version in the configuration file, you can easily change the tool version. You can try a new version or downgrade the tool easily.

Change tool version per configuration​

You can manage tool version per configuration file. You can install multiple versions in the same machine and switch them per project.

Manage your tools as dotfiles​

By managing your aqua configuration file in Git repository such as your dotfiles, you can manage your tools as code. You can set up your new laptop and use the same tool version in your multiple laptops easily.

Manage tools for your team and organization​

aqua supports not only personal use but also team and organization use. By managing aqua configuration for your team and organization in Git Repository, you can manage tools for your team and organization as code. New joiners can set up their laptops quickly and you can distribute tools easily.

Manage tools for a repository​

By adding aqua configuration file to a repository, you can manage tools for the repository with aqua. aqua manages tool versions declaratively, so you always only have to execute the same command. So new contributors can set up quickly and you can update tools easily. You don’t have to maintain the document about required tools and you don’t have to investigate how to install them.

Install tools managed in the private GitHub Repositories​

aqua supports installing tools from the private GitHub Repositories. It’s useful to distribute your organization’s private tools.

Use aqua in CI​

There are GitHub Actions and CircleCI Orb for aqua, so you can install tools with aqua easily in CI too. You can use the same version in both local development and CI.

By the way, many GitHub Actions install the tool automatically before executing it. It’s very easy to use, but there are some problems.

  • Some GitHub Actions don’t force to pin tool versions, which may cause the problem due to the difference of tool version
  • When you specify tool version in inputs, you have to update it continuously but it’s not easy
  • You can’t install tools in your laptop for local development with GitHub Actions. You have to install tools by the other way
  • It’s difficult to unify tool versions in local development and CI

aqua solves the above problems.

  • aqua forces to pin tool versions
  • With Renovate Preset Config for aqua, you can update tools easily with Renovate
  • aqua supports both local development and CI
  • You can use the same configuration in both local development and CI, so you can unify tool versions easily

Registry​

Registry is aqua’s mechanism to manage the list of installable tools and how to install them. Registry is a simple YAML. You can write Registry in aqua configuration, or you can read it from other local files and GitHub Repositories. You can manage private Registry in private GitHub Repository.

We maintain the Standard Registry and you can install tools in the Registry easily without writing Registry by your self.

Conclusion​

In this post, I introduced the CLI tool aqua, which manages CLI tool version with YAML. Let’s try Quick Start.

· 6 min read
Shunsuke Suzuki

Original Post: https://dev.to/suzukishunsuke/aqua-declarative-cli-version-manager-1ibe

In this post, I introduce aqua, which is a declarative CLI Version Manager. You can install CLI tools and manage their versions with YAML declaratively. Mainly the following use cases are assumed.

  • Install tools in CI/CD
  • Install tools for repository's local development
  • Install tools in your laptop

aqua supports the Lazy Install and Sharable Configuration mechanism named Registry. Compared to other package manager like Homebrew, aqua supports switching tool versions per aqua.yaml. Of course, you can use aqua with other package managers too.

You can install aqua with aqua-installer.

$ curl -sSfL \
  https://raw.githubusercontent.com/aquaproj/aqua-installer/v1.0.0/aqua-installer |
  bash -s -- -i ~/bin/aqua -v v1.9.0

You can install aqua with Homebrew too.

$ brew install aquparoj/aqua/aqua

For example, let's install jq with aqua. Write the following aqua.yaml.

registries:
- type: standard
  ref: v2.19.0 # renovate: depName=aquaproj/aqua-registry
packages:
- name: stedolan/jq
  version: jq-1.5

And run aqua i -l.

$ aqua i -l

The option -l is important. By this option, the symbolic links are created in ~/.aqua/bin but the downloading tools is skipped. This is the feature named Lazy Install.

Tools are installed in ~/.local/share/aquaproj-aqua. Let's add ~/.local/share/aquaproj-aqua/bin to the environment variable PATH.

$ export PATH=$HOME/.local/share/aquaproj-aqua/bin:$PATH

Let's check if jq installed correctly.

$ jq --version
INFO[0000] download and unarchive the package            package_name=jq package_version=jq-1.5 program=aqua registry=standard
jq-1.5

The output INFO[0000] download and unarchive the package package_name=jq package_version=jq-1.5 program=aqua registry=standard indicates that jq is installed automatically before jq is executed.

aqua searches the configuration file [.]aqua.y[a]ml from the current directory to the root directory.

$ cd foo
$ jq --version
jq-1.5

$ cd ../..
$ jq --version
FATA[0000] aqua failed                                   error="command is not found" exe_name=jq program=aqua

Let's update jq from 1.5 to 1.6.

packages:
- name: stedolan/jq
  version: jq-1.6

And run jq --version. Before jq is executed, jq is installed automatically.

$ jq --version
INFO[0000] download and unarchive the package            package_name=jq package_version=jq-1.6 program=aqua registry=standard
jq-1.6

Let's downgrade jq from 1.6 to 1.5.

packages:
- name: stedolan/jq
  version: jq-1.5
$ jq --version
jq-1.5

The version of tool is changed seamlessly. You don't have to execute aqua.

By adding aqua.yaml in each Git repositories, you can manage tools for each repositories. Developers can use the same version, which prevents the problem due to the difference of tool versions. aqua supports both MacOS and Linux, so even if you are working on MacOS and CI is run on Linux, you can manage tools with the same aqua.yaml.

aqua installs tools in ~/.local/share/aquaproj-aqua and shares tools across multiple aqua.yaml, so the same version of the same tool is installed only at once. It saves time and disk usage.

aqua supports the Global configuration. This is useful to install tools in your laptop regardless the specific project. Like dotfiles, it is good to manage the Global Configuration with Git and share it with your multiple laptops.

Registry​

aqua supports the Sharable Configuration mechanism named Registry.

You can install jq with the simple configuration.

registries:
- type: standard
  ref: v2.19.0

packages:
- name: stedolan/jq
  version: jq-1.5

In the above configuration, the Standard Registry is being used. The Standard Registry is the Registry maintained by aqua's maintainers.

Please see the configuration.

https://github.com/aquaproj/aqua-registry/blob/v2.19.0/pkgs/stedolan/jq/registry.yaml

packages:
  - type: github_release
    repo_owner: stedolan
    repo_name: jq
    asset: "jq-{{.OS}}"
    format: raw
    description: Command-line JSON processor
    replacements:
      darwin: osx-amd64
      linux: linux64
      windows: win64.exe

This is the configuration to download jq from GitHub Releases. Using the Standard Registry, you can install tools very easily without complicated configuration.

You can search the tool from the Registries with aqua g command. Please add the Registries to your aqua.yaml's registries, and run aqua g.

registries:
- type: standard
  ref: v2.19.0
$ aqua g

aqua g launches the interactive UI and you can search the package by fuzzy search.

  influxdata/influx-cli (standard) (influx)                     ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
  newrelic/newrelic-cli (standard) (newrelic)                   │  cli/cli
  pivotal-cf/pivnet-cli (standard) (pivnet)                     │
  scaleway/scaleway-cli (standard) (scw)                        │  https://github.com/cli/cli
  tfmigrator/cli (standard) (tfmigrator)                        │  GitHub’cs official command line tool
  aws/copilot-cli (standard) (copilot)                          │
  create-go-app/cli (standard) (cgapp)                          │
  harness/drone-cli (standard) (drone)                          │
  sigstore/rekor (standard) (rekor-cli)                         │
  getsentry/sentry-cli (standard)                               │
  grafana/loki/logcli (standard)                                │
  knative/client (standard) (kn)                                │
  rancher/cli (standard) (rancher)                              │
  tektoncd/cli (standard) (tkn)                                 │
  civo/cli (standard) (civo)                                    │
  dapr/cli (standard) (dapr)                                    │
  mongodb/mongocli (standard)                                   │
  openfaas/faas-cli (standard)                                  │
> cli/cli (standard) (gh)                                       │
  50/433                                                        │
> cli                                                           └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─

If the tool you need isn't found, please create the issue or send the pull request to the Standard Registry! By adding various packages to the Standard Registry, aqua becomes more useful and attractive. Your contribution is needed!

It is also easy to create your own Registries. Just create GitHub Repositories and add Registry Configuration like the Standard Registry and add it to aqua.yaml's registries. The private repository is also supported.

e.g.

registries:
  - name: aquaproj/aqua-registry
    type: github_content
    repo_owner: aquaproj
    repo_name: aqua-registry
    ref: v2.19.0
    path: registry.yaml

Cotinuous update by Renovate​

aqua manages package and registry versions, so it is important to update them continuously. aqua doesn't provide sub commands like aqua update or options like aqua install --update. We recommend managing aqua.yaml with Git and update versions by Renovate.

Using Renovate's Regex Manager, you can update versions.

The Renovate Preset Configuration https://github.com/aquaproj/aqua-renovate-config is useful. For the detail, please see the README.

Summary​

In this post, I introduced aqua, which is a declarative CLI Version Manager. You can install CLI tools and manage their versions with YAML declaratively. aqua supports the Lazy Install and Sharable Configuration mechanism named Registry.

You can search tools from Registries by aqua g command. If the tool you need isn't found, please create the issue or send the pull request to the Standard Registry! By adding various packages to the Standard Registry, aqua becomes more useful and attractive. Your contribution is needed!