aqua

README

aqua

CLI Version manager.

Index

• Slide (Speaker Deck)
• Tutorial
• Usage
• Configuration
• Registry
• Continuous update by Renovate

Overview

You can install CLI tools and manage their versions with declarative YAML configuration aqua.yaml.

e.g. Install jq, direnv, and fzf with aqua.

registries:
- type: standard
  ref: v0.2.4 # renovate: depName=suzuki-shunsuke/aqua-registry

packages:
- name: jq
  registry: standard
  version: jq-1.6
- name: direnv
  registry: standard
  version: v2.28.0 # renovate: depName=direnv/direnv
- name: fzf
  registry: standard
  version: 0.27.2 # renovate: depName=junegunn/fzf

After writing the configuration, you can install them by aqua i.

$ aqua i

aqua i installs all packages all at once. Tools are installed in ~/.aqua/pkg and symbolic links are created in ~/.aqua/bin, so please add ~/.aqua/bin to the environment variable PATH.

It takes a long time to install many tools all at once, and some tools might not be actually needed.

So instead of aqua i let's execute aqua i --only-link.

$ aqua i --only-link

--only-link creates symbolic links to aqua-proxy in ~/.aqua/bin but skipping the downloading and installing tools. When you execute the tool, the tool is installed automatically if it isn't installed yet before it is executed. We call this feature as lazy install. By the lazy install, you don't have to execute aqua explicitly after changing the tool's version. When aqua.yaml is managed with Git, the lazy install is very useful because aqua.yaml is updated by git pull then the update is reflected automatically.

By adding aqua.yaml in your Git repositories, you can manage tools per repository. You can change the version of tools per project.

aqua installs the tools in the shared directory ~/.aqua, so the same version of the same tool is installed only at once. It saves the time and the disk usage.

aqua supports the mechanism named Registry. You can share and reuse the aqua configuration, so it makes easy to write aqua.yaml.

registries:
- type: standard
  ref: v0.2.4 # renovate: depName=suzuki-shunsuke/aqua-registry

packages:
- name: direnv
  registry: standard
  version: v2.28.0 # renovate: depName=direnv/direnv

In the above configuration, the standard Registry is used so you can install direnv easily.

By the command aqua generate, you can check if the registry supports the tool you need and write the configuration quickly.

$ aqua g

aqua g launches the interactive UI and you can select the package and it's version interactively.

  direnv (standard)
  consul (standard)
  conftest (standard)
> golangci-lint (standard)
  47/47
>

If the selected package type is github_release, you can select the package version interactively.

  v1.40.0
  v1.40.1
  v1.41.0
  v1.41.1
> v1.42.0
  30/30
>

After selecting the package and its version, the configuration is outputted.

$ aqua g
- name: golangci-lint
  registry: standard
  version: v1.42.0

If the Registries don't support the tool, you can send the pull request to the registry or create your own Registry or add the configuration in aqua.yaml as inline Registry.

Quick Start

Install aqua.

$ curl -sSfL https://raw.githubusercontent.com/suzuki-shunsuke/aqua-installer/v0.1.2/aqua-installer | bash -s -- -i bin/aqua
$ export PATH=$PWD/bin:$HOME/.aqua/bin:$PATH
$ export GITHUB_TOKEN=<your personal access token>

Write aqua.yaml.

packages:
- name: jq
  registry: standard
  version: jq-1.5

registries:
- type: standard
  ref: v0.2.4 # renovate: depName=suzuki-shunsuke/aqua-registry

Install tools.

$ aqua i

Tools are installed successfully.

$ jq --version
jq-1.5

Edit aqua.yaml.

$ sed -i "s/jq-1\.5/jq-1.6/" aqua.yaml

Run jq again, then jq's new version is installed automatically and jq is run.

$ jq --version
jq-1.6

Main Usecase

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

Feature

• Declarative YAML Configuration
  • You don't have to execute commands imperatively to install tools
• Manage versions per project
  • You can change tools version per project
• Install tools when they are executed
  • When you execute the tool which isn't installed yet, aqua installs the tool and execute the tool
• Share tools across projects
  • aqua installs tools in the shared directory ~/.aqua. It saves time and disk to install tools
• Ecosystem named Registry - it eases to write aqua configuration
  • You can share and reuse the aqua configuration. We provide the standard registry too

Install

Please download a binary from the Release Page.

Or you can install aqua quickly with aqua-installer.

e.g.

$ curl -sSfL https://raw.githubusercontent.com/suzuki-shunsuke/aqua-installer/v0.1.2/aqua-installer | bash

GitHub Actions

e.g.

- uses: suzuki-shunsuke/aqua-installer@v0.1.2
  with:
    version: v0.3.1
    install_path: /tmp/bin/aqua

Where are tools installed?

• Symbolic links are created in $HOME/.aqua/bin, so add this to the environment variable PATH
• Tools are installed in $HOME/.aqua/pkgs

(your working directory)/
  aqua.yaml
~/.aqua/ # $AQUA_ROOT_DIR (default ~/.aqua)
  bin/
    aqua-proxy (symbolic link to aqua-proxy)
    <tool> (symbolic link to aqua-proxy)
  global/
    aqua.yaml # global configuration
  pkgs/
    github_release/
      github.com/
        suzuki-shunsuke/
          aqua-proxy/
            v0.1.0/
              aqua-proxy_darwin_amd64.tar.gz
                aqua-proxy
  registries/
    github_content/
      github.com/
        suzuki-shunsuke/
          aqua-registry/
            v0.1.1-0/
              registry.yaml

Related Projects

• aqua-proxy
• aqua-installer: Install aqua quickly
• aqua-registry: Standard Registry
• aqua-config-renovate: Renovate Configuration to update packages and registries

Example

• suzuki-shunsuke/my-aqua-config
• suzuki-shunsuke/example-aqua

Change Log

Please see Releases.

Blog

• 2021-08-28 aqua - CLI ツールのバージョン管理
• 2021-09-04 aqua v0.1.0 から v0.5.0 での変更点
• 2021-09-05 aqua の設定ファイルをインタラクティブに生成する generate コマンド

License

MIT