README
¶
aqua
Declarative CLI Version manager. Support Lazy Install and Sharable configuration mechanism named Registry. Switch versions seamlessly.
Index
- Slide (Speaker Deck)
- Tutorial
- Usage
- Configuration
- Registry
- Continuous update by Renovate
- How does Lazy Install works?
- How to uninstall aqua
- How to clean unused packages
Blog
- English
- Japanese
Note: Windows isn't supported
Currently, aqua doesn't support Windows.
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.6.0 # 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/pkgs 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 -l.
$ aqua i -l
aqua i -l 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.6.0 # 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.3/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.6.0 # 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
- Install tools for your project's local development
- Install tools in your laptop
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
- aqua installs tools in the shared directory
- 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.3/aqua-installer | bash
GitHub Actions
e.g.
- uses: suzuki-shunsuke/aqua-installer@v0.1.3
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 variablePATH - 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-renovate-config: Renovate Configuration to update packages and registries
- Third Party Projects
- int128/aqua-action - Action to install packages using aqua
Example
Change Log
Please see Releases.
Versioning Policy
We are Conforming suzuki-shunsuke/versioning-policy v0.1.0, which is compatible with Semantic Versioning 2.0.0.
Directories