Skip to main content

Home

How to learn aqua​

aqua has a lot of documents, so it's hard to read all of them. But don't worry. You don't have to read all of them all at once.

Here is a brief overview of how to learn aqua.

  1. To install aqua, please read Install
  2. To learn the basic usage, please try Tutorial. aqua is easy to use, so you would be able to use aqua in a short time
  3. To learn the overview, please see Demo, top page, and this page (Introduction, Why aqua, Comparison)
  4. To learn advanced usage, please read Guides
  5. To contribute to Standard Registry (Add new packages, fix bugs), please read Contributing
  6. To develop custom Registry, please read Develop a Registry

If you have any question, please contact us.

For Japanese​

We published an e-book about aqua for free. Please read it!

aqua CLI Version Manager 入門 (2023-10-01)

Introduction​

aqua is a declarative CLI Version Manager written in Go. You can manage tool versions with YAML.

e.g. aqua.yaml

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 short demo would be useful to understand aqua.

asciicast

You can install tools simply by aqua i command.

$ aqua i

aqua supports various tools officially. You can search tools interactively by aqua g command.

$ aqua g
  newrelic/newrelic-cli (standard) (newrelic)                   ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
  pivotal-cf/pivnet-cli (standard) (pivnet)                     │  cli/cli
  scaleway/scaleway-cli (standard) (scw)                        │
  tfmigrator/cli (standard) (tfmigrator)                        │  https://cli.github.com/
  aws/copilot-cli (standard) (copilot)                          │  GitHub’cs official command line tool
  codeclimate/test-reporter (standard)                          │
  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/399                                                        │
> cli                                                           └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─

To add supported tools, please see here.

Usecase​

  1. Install tools in your laptop globally. You can also manage tools in your dotfiles repository
  2. Manage tools for projects
  3. Manage tools for your organization and team
  4. Distribute private tools in your organization

Why aqua?​

  • Change tool versions per project
    • Unlike Package Manager such as Homebrew, aqua supports changing tool version per project
  • Unify tool versions to prevent problems due to version difference
    • aqua makes you specify tool versions strictly
    • aqua supports cross platforms and provides the unified way to manage tools both in local development and CI
  • Easy to use
    • This is so important for introducing a tool to a project and having developers use it
  • Painless
    • aqua installs tools automatically when they are triggered. You don't have to run aqua i everytime tools are updated
    • Continuous update by Renovate
    • Easy to support new tools. You don't have to maintain plugins or something yourself. You only have to send a pull request to the Standard Registry, which is very easy
    • 👋 Good bye shell script
      • You don't have to write similar shell scripts to install tools many times. You only have to manage tools declaratively with YAML and run aqua i
  • 🛡️ Security
  • Lower overhead than container
    • You don't have to suffer from container specific issues
  • Support private packages

Strict Version Control​

The difference of tool version often causes troubles. In the team development, if developers use different tool versions each others, you would suffer from troubles due to the version difference. And if the tool version in your laptop is different from the tool version in CI, you would suffer from the same trouble.

image

And if multiple projects require the different tool versions, you have to switch the tool version per project somehow.

Package managers such as Homebrew and apt don't support switching tool versions.

aqua forces to pin tool versions and supports switching tool versions per project. You can upgrade a tool temporaroly and rollback the upgrade easily only by editing aqua.yaml.

Of course, aqua supports Monorepo which uses different tool versions per service as well.

Installing latest version in CI is danger​

If you install a tool in CI, the tool should be version controlled to avoid troubles. Installing latest version is useful but danger because the latest version is changed suddenly and unexpected trouble may occur. Your CI would be broken suddenly though you don't change any code. Many GitHub Actions install latest version by default.

aqua forces to pin tool versions and doesn't allow to install latest version.

Easy to install tools for your projects​

You can list up tools and their versions for your project in aqua.yaml. Developers can install tools easily only by running aqua i [-l]. You don't have to write the document about which tools are required and how to install them.

👋 Good bye shell script​

You may install tools by shell scripts.

e.g.

#!/usr/bin/env bash

set -eu

tempdir=$(mktemp -d)
cd "$tempdir"
curl -Lq -O https://github.com/suzuki-shunsuke/tfcmt/releases/download/v4.2.0/tfcmt_darwin_amd64.tar.gz
tar xvzf tfcmt_darwin_amd64.tar.gz
chmod a+x tfcmt
sudo mv tfcmt /usr/local/bin
rm -R "$tempdir"

Shell scripts have some issues.

  • You have to maintain scripts per tool
  • You have to update the tool version somehow
    • In many cases, the tool isn't updated and the old version is used for a long time
  • The script isn't portable
    • The above script supports only darwin/amd64
  • The script doesn't verify the checksum
    • If you verify the checksum in shell script, you have to update the checksum along with the version. It's bothersome

Using aqua, you don't have to maintain shell scripts anymore. aqua supports updating tools by Renovate and checksum verification. aqua works on cross platform. aqua supports updating not only versions but also checksums automatically.

Continuous update by Renovate​

If tools are version controlled, they should be updated continuously. Otherwise, they would become old soon, which causes several issues.

aqua provides Renovate Config Preset for continuous update by Renovate. Using this preset, you can easily update tools by Renovate.

ref. Update packages by Renovate

info

As of aqua v2.14.0, aqua also supports update command.

🛡️ Security​

You should verify the checksum of the tool before installing the tool. Otherwise, the tool may be tampered and the malicious code may be executed.

Unfortunately, many shell scripts, asdf plugins, and GitHub Actions don't verify the checksum.

On the other hand, aqua supports the checksum verification.

ref. Security

Easy to use​

If you use tools by yourself, you can use any tools you like freely even if the tool is difficult and the learning cost is high. But when you introduce a tool to your team and organization, it is important that the tool is easy to use.

Even if you have a high motivation to learn them, other members don't necessarily have the motivation. They have to focus on their own tasks and don't have a time to learn new tools. Then you wouldn't be able to introduce the tool to your team well and even if you introduce it some of other members wouldn't use it.

Compared with alternatives such as asdf and tea, aqua is much easy to use. Other members have to do only the following things.

  1. Install aqua in their laptops once
  2. Run aqua i -l

aqua provides various features, but other members can use aqua without learning them.

Easy to support new tools​

aqua has the central Registry (Standard Registry) and you can add new tools to the Registry. You don't have to maintain plugins or something yourself. You only have to create issues or pull requests. To send a pull request you have to write Registry Configuration, but aqua provides the tool to scaffold Registry Configuration and create pull requests, so you can send pull requests easily. Registry Configuration is a declarative YAML files, so you don't have to write shell scripts or something. Declarative YAML files are much easier to maintain than scripts.

Many contributors have already contributed to Standard Registry. Your contribution is welcome!

Comparison​

caution

We are not necessarily familiar with compared tools. So maybe the description about them is wrong. Your contribution is welcome.

Compared with Homebrew​

You can use Homebrew to install tools aqua can't install.

Compared with asdf​

aqua doesn't force to manage a tool by aqua in a project even if aqua is used to manage the tool in the other project​

For example, you can't use both asdf and nvm to manage Node.js in the same laptop. If you develop a project A using asdf to manage Node.js in your laptop, you can't develop a project B using nvm in the same laptop.

On the other hand, aqua can be used along with alternatives in the same laptop.

Please see Use aqua combined with other version manager such as asdf.

Use aqua along with asdf​

asdf supports language runtimes such as Node.js, Python, Ruby, and so on, though aqua can't support them. You can use asdf for them and can use aqua for other tools.

Compared with GitHub Actions​

Restriction​

Please see Restriction.

Twitter​

We share news about aqua using a Twitter Account @aquaclivm. We check tweets about aqua, but it is difficult to search tweets about aqua with the keyword "aqua" because aqua is a very common word. So when you tweet about aqua, please mention @aquaclivm or use the hash tag #aquaclivm.

GitHub Sponsor​

We'll really appreciate if you become a sponsor of this project!

https://github.com/sponsors/aquaproj