A CLI version manager for the discriminating CLI connoisseur, this tool is great to install binaries both at a global level and a project level.
If you are using asdf, I highly recommend this as an alternative, with the caveat of it not managing python, ruby, or other runtimes.
It’s focused on CLI development tools, and providing a global or project-level version configuration that automatically installs on demand.
Aqua runs as a proxy for the invoked CLIs, which means it automatically handles installing the called tool if it’s missing, on demand, further cutting down initial setup time.
You can even use it in docker images or CI and have a single version pinned file helping the local and CI tools be similar.
It’s more secure than asdf by default.
Quick Start includes install commands to setup.
I use curl-based install mostly: Install
1
|
brew install aquaproj/aqua/aqua
|
1
|
pwsh -NoLogo -Command "go install github.com/aquaproj/aqua/v2/cmd/aqua@latest"
|
1
|
export PATH="${AQUA_ROOT_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/aquaproj-aqua}/bin:$PATH"
|
The options below are one for max flexibility in honoring the XDG_Directory standard; the other just assumes .local.
1
2
3
4
5
6
7
|
$ENV:XDG_CONFIG_HOME = $ENV:XDG_CONFIG_HOME ? $ENV:XDG_CONFIG_HOME : (Join-Path $HOME '.config')
$ENV:XDG_CACHE_HOME = $ENV:XDG_CACHE_HOME ? $ENV:XDG_CACHE_HOME : (Join-Path $HOME '.cache')
$ENV:XDG_DATA_HOME = $ENV:XDG_DATA_HOME ? $ENV:XDG_DATA_HOME : (Join-Path $HOME '.local' 'share')
$ENV:PATH = ([io.path]::Combine($HOME,'.local','share','aquaproj-aqua', 'bin')), $ENV:PATH -join [IO.Path]::PathSeparator
# OR FOR MAX FLEXIBILITY
$ENV:PATH = ([io.path]::Combine($ENV:XDG_DATA_HOME, 'aquaproj-aqua', 'bin')), $ENV:PATH -join [IO.Path]::PathSeparator
|
1
|
[Environment]::SetEnvironmentVariable('PATH', ((Join-Path $ENV:LOCALAPPDATA 'aquaproj-aqua' 'bin') , $ENV:PATH -join [IO.Path]::PathSeparator), 'Machine')
|
1
|
$ENV:PATH = ((Join-Path $ENV:LOCALAPPDATA 'aquaproj-aqua' 'bin') , $ENV:PATH -join [IO.Path]::PathSeparator)
|
To create these files, navigate to the directory and run aqua init && aqua init-policy.
Run aqua policy allow "${XDG_CONFIG_HOME:-$HOME/.config}/aqua/aqua-policy.yaml" to allow global tooling that’s customized.
1
2
3
|
export PATH="${AQUA_ROOT_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/aquaproj-aqua}/bin:$PATH"
export AQUA_GLOBAL_CONFIG=${XDG_CONFIG_HOME:-$HOME/.config}/aqua/aqua.yaml
# export AQUA_POLICY_CONFIG=${XDG_CONFIG_HOME:-$HOME/.config}/aqua/aqua-policy.yaml
|
1
2
3
|
$RootLocation = $ENV:AQUA_ROOT_DIR ?? (Join-Path $ENV:XDG_DATA_HOME 'aquaproj-aqua' 'bin') ?? (Join-Path "$HOME/.local/share" 'aquaproj-aqua' 'bin')
$RootLocationWithBin = Join-Path $RootLocation 'bin'
$ENV:PATH = $RootLocationWithBin, $ENV:PATH -join [IO.Path]::PathSeparator
|
Here’s an example of what I drop into the global config for managing my global default for Go and other common CLI tools.
This is the custom location for packages not in the standard registry.
While I recommend contributing upstream (it’s really simple), sometimes less shareable tools for specific needs make sense to include here.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
|
---
packages:
- type: go_install
name: mage-select
path: github.com/iwittkau/mage-select
description: CLI frontend for mage based on promptui.
search_words:
- mage
- module
- go
- type: github_release
repo_owner: alihanyalcin
repo_name: gomup
link: https://github.com/alihanyalcin/gomup/releases/
asset: 'gomup_{{trimV .Version}}_{{.OS}}_{{.Arch}}.tar.gz'
description: gomUP is a tool to keep track of outdated dependencies and upgrade them to the latest version. Designed for monorepo Go projects and Go projects that contain multiple modules.
search_words:
- gomod
- module
replacements:
darwin: Darwin
linux: Linux
windows: Windows
386: i386
amd64: x86_64
|
Used to allow the custom tooling that aqua can handle outside the standard packages.
For example, custom cargo install or go install packages.
1
2
3
4
5
6
7
8
9
10
11
12
|
---
# aqua Policy
# https://aquaproj.github.io/docs/tutorial-extras/policy-as-code
registries:
- type: standard
ref: semver(">= 3.0.0")
- name: local
type: local
path: registry.yaml
packages:
- registry: standard
- registry: local
|
This is focused on ubuntu-latest as the windows agent has some quirks not addressed in this format.
This still uses pwsh on the ubuntu agent to avoid me having to rework logic for 2 platforms.
1
2
3
4
5
|
- bash: |
echo "##vso[task.prependpath]${AQUA_ROOT_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/aquaproj-aqua}/bin"
export PATH="${AQUA_ROOT_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/aquaproj-aqua}/bin:$PATH"
curl -sSfL https://raw.githubusercontent.com/aquaproj/aqua-installer/v2.3.0/aqua-installer | bash -s
displayName: install-aqua
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
- pwsh: |
&curl -sSfL https://raw.githubusercontent.com/aquaproj/aqua-installer/v2.1.1/aqua-installer | bash -s -- -v v2.3.6
try {
$ENV:PATH = ([io.path]::Combine($HOME,'.local','share','aquaproj-aqua', 'bin')), $ENV:PATH -join [IO.Path]::PathSeparator
}
catch {
Write-Warning "Unable to load aqua: $($_.Exception.Message)"
}
Write-Host "aqua version: $(& aqua version)"
&aqua update-aqua
Write-Host "aqua version (after update): $(& aqua version)"
$env:PATH = (Join-Path $(aqua root-dir) 'bin'), $env:PATH -join [IO.Path]::PathSeparator
Write-Host "run aqua install --tags first"
&aqua install --tags first
Write-Host "install remaining aqua tools"
aqua install --tags MYCUSTOM TAG # 👈 narrow down what you invoke
$ENV:PATH = (Join-Path $HOME '.config' @('aquaproj-aqua','bin')), $ENV:PATH -join [IO.Path]::PathSeparator
mage # ..... 👈 invoke commands now that things are installed
|
Webmentions
(No webmentions yet.)