Usage
$ aqua --help
NAME:
aqua - Version Manager of CLI. https://aquaproj.github.io/
USAGE:
aqua [global options] command [command options]
VERSION:
2.44.1 (003f26d72ca2ed0d680e46a7fa35179164acd7d9)
COMMANDS:
init Create a configuration file if it doesn't exist
install, i Install tools
generate, g Search packages in registries and output the configuration interactively
update-aqua, upa Update aqua
update-checksum, upc Create or Update aqua-checksums.json
update, up Update registries and packages
completion Output shell completion script for bash, zsh, or fish
which Output the absolute file path of the given command
info Show information
remove, rm Uninstall packages
vacuum Remove unused installed packages
cp Copy executable files in a directory
policy Manage Policy
init-policy [Deprecated] Create a policy file if it doesn't exist
exec Execute tool
list List packages in Registries
generate-registry, gr Generate a registry's package configuration
version Show version
root-dir Output the aqua root directory (AQUA_ROOT_DIR)
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--log-level value log level [$AQUA_LOG_LEVEL]
--config value, -c value configuration file path [$AQUA_CONFIG]
--disable-cosign Disable Cosign verification (default: false) [$AQUA_DISABLE_COSIGN]
--disable-slsa Disable SLSA verification (default: false) [$AQUA_DISABLE_SLSA]
--disable-github-artifact-attestation Disable GitHub Artifact Attestations verification (default: false) [$AQUA_DISABLE_GITHUB_ARTIFACT_ATTESTATION]
--trace value trace output file path
--cpu-profile value cpu profile output file path
--help, -h show help
--version, -v print the version
aqua init
$ aqua init --help
NAME:
aqua init - Create a configuration file if it doesn't exist
USAGE:
aqua init [command options] [<created file path. The default value is "aqua.yaml">]
DESCRIPTION:
Create a configuration file if it doesn't exist
e.g.
$ aqua init # create "aqua.yaml"
$ aqua init foo.yaml # create foo.yaml
$ aqua init -u # Replace "packages:" with "import_dir: imports"
$ aqua init -i <directory path> # Replace "packages:" with "import_dir: <directory path>"
$ aqua init -d # Create a directory "aqua" and create "aqua/aqua.yaml"
OPTIONS:
--use-import-dir, -u Use import_dir (default: false)
--import-dir value, -i value import_dir
--create-dir, -d Create a directory named aqua and create aqua.yaml in it (default: false)
--help, -h show help
aqua install
$ aqua install --help
NAME:
aqua install - Install tools
USAGE:
aqua install [command options]
DESCRIPTION:
Install tools according to the configuration files.
e.g.
$ aqua i
If you want to create only symbolic links and want to skip downloading package, please set "-l" option.
$ aqua i -l
By default aqua doesn't install packages in the global configuration.
If you want to install packages in the global configuration too,
please set "-a" option.
$ aqua i -a
You can filter installed packages with package tags.
e.g.
$ aqua i -t foo # Install only packages having a tag "foo"
$ aqua i --exclude-tags foo # Install only packages not having a tag "foo"
OPTIONS:
--only-link, -l create links but skip downloading packages (default: false)
--test This flag was deprecated and had no meaning from aqua v2.0.0. This flag will be removed in aqua v3.0.0. https://github.com/aquaproj/aqua/issues/1691 (default: false)
--all, -a install all aqua configuration packages (default: false)
--tags value, -t value filter installed packages with tags
--exclude-tags value exclude installed packages with tags
--help, -h show help
aqua generate
$ aqua generate --help
NAME:
aqua generate - Search packages in registries and output the configuration interactively
USAGE:
aqua generate [command options] [<registry name>,<package name> ...]
DESCRIPTION:
Search packages in registries and output the configuration interactively.
If no argument is passed, interactive fuzzy finder is launched.
$ aqua g
influxdata/influx-cli (standard) (influx) ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
newrelic/newrelic-cli (standard) (newrelic) │ cli/cli
pivotal-cf/pivnet-cli (standard) (pivnet) │
scaleway/scaleway-cli (standard) (scw) │ https://cli.github.com/
tfmigrator/cli (standard) (tfmigrator) │ GitHub’cs official command line tool
aws/copilot-cli (standard) (copilot) │
codeclimate/test-reporter (standard) │
create-go-app/cli (standard) (cgapp) │
harness/drone-cli (standard) (drone) │
sigstore/rekor (standard) (rekor-cli) │
getsentry/sentry-cli (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) │
48/380 │
> cli └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
Please select the package you want to install, then the package configuration is outptted.
You can select multiple packages by tab key.
Please copy and paste the outputted configuration in the aqua configuration file.
$ aqua g # tfmigrator/cli is selected
- name: tfmigrator/cli@v0.2.1
You can update the configuration file directly with "-i" option.
$ aqua g -i
You can update an imported file with "-o" option.
$ aqua g -o aqua/pkgs.yaml
You can pass packages with positional arguments.
$ aqua g [<registry name>,<package name>[@<version>] ...]
$ aqua g standard,cli/cli standard,junegunn/fzf standard,suzuki-shunsuke/tfcmt@v3.0.0
- name: cli/cli@v2.2.0
- name: junegunn/fzf@0.28.0
- name: suzuki-shunsuke/tfcmt@v3.0.0
You can omit the registry name if it is "standard".
$ aqua g cli/cli
- name: cli/cli@v2.2.0
With "-f" option, you can pass packages.
$ aqua g -f packages.txt # list of <registry name>,<package name>
- name: cli/cli@v2.2.0
- name: junegunn/fzf@0.28.0
- name: tfmigrator/cli@v0.2.1
$ cat packages.txt | aqua g -f -
- name: cli/cli@v2.2.0
- name: junegunn/fzf@0.28.0
- name: tfmigrator/cli@v0.2.1
$ aqua list | aqua g -f - # Generate configuration to install all packages
You can omit the registry name if it is "standard".
echo "cli/cli" | aqua g -f -
- name: cli/cli@v2.2.0
You can select a version interactively with "-s" option.
By default, aqua g -s will only display 30 versions of package.
Use --limit/-l to change it. Non-positive number refers to no limit.
# Display 30 versions of selected by default
$ aqua g -s
# Display all versions of selected package
$ aqua g -s -l -1
# Display 5 versions of selected package
$ aqua g -s -l 5
The option "-pin" is useful to prevent the package from being updated by Renovate.
$ aqua g -pin cli/cli
- name: cli/cli
version: v2.2.0
With -detail option, aqua outputs additional information such as description and link.
$ aqua g -detail cli/cli
- name: cli/cli@v2.2.0
description: GitHub’s official command line tool
link: https://github.com/cli/cli
With -g option, aqua reads a first global configuration file.
$ aqua g -g cli/cli
You can add packages to a first global configuration file with -g and -i option.
$ aqua g -g -i cli/cli
OPTIONS:
-f value the file path of packages list. When the value is "-", the list is passed from the standard input
-i Insert packages to configuration file (default: false)
--pin Pin version (default: false)
-g Insert packages in a global configuration file (default: false)
--detail, -d Output additional fields such as description and link (default: false) [$AQUA_GENERATE_WITH_DETAIL]
-o value inserted file
--select-version, -s Select the installed version interactively. Default to display 30 versions, use --limit/-l to change it. (default: false)
--limit value, -l value The maximum number of versions. Non-positive number refers to no limit. (default: 30)
--help, -h show help
aqua update-aqua
$ aqua update-aqua --help
NAME:
aqua update-aqua - Update aqua
USAGE:
aqua update-aqua [command options]
DESCRIPTION:
Update aqua.
e.g.
$ aqua update-aqua [version]
aqua is installed in $AQUA_ROOT_DIR/bin.
By default the latest version of aqua is installed, but you can specify the version with argument.
e.g.
$ aqua update-aqua # Install the latest version
$ aqua update-aqua v1.20.0 # Install v1.20.0
OPTIONS:
--help, -h show help
aqua update-checksum
$ aqua update-checksum --help
NAME:
aqua update-checksum - Create or Update aqua-checksums.json
USAGE:
aqua update-checksum [command options]
DESCRIPTION:
Create or Update aqua-checksums.json.
e.g.
$ aqua update-checksum
By default aqua doesn't update aqua-checksums.json of the global configuration.
If you want to update them too,
please set "-a" option.
$ aqua update-checksum -a
By default, aqua update-checksum doesn't remove existing checksums even if they aren't unused.
If -prune option is set, aqua unused checksums would be removed.
$ aqua update-checksum -prune
OPTIONS:
--all, -a Create or Update all aqua-checksums.json including global configuration (default: false)
--deep This flag was deprecated and had no meaning from aqua v2.0.0. This flag will be removed in aqua v3.0.0. https://github.com/aquaproj/aqua/issues/1769 (default: false)
--prune Remove unused checksums (default: false)
--help, -h show help
aqua update
$ aqua update --help
NAME:
aqua update - Update registries and packages
USAGE:
aqua update [command options]
DESCRIPTION:
Update registries and packages.
If no argument is passed, all registries and packages are updated to the latest.
# Update all packages and registries to the latest versions
$ aqua update
This command has an alias "up"
$ aqua up
This command gets the latest version from GitHub Releases, GitHub Tags, and crates.io and updates aqua.yaml.
This command doesn't update commit hashes.
This command doesn't install packages.
This command updates only a nearest aqua.yaml from the current directory.
If this command finds a aqua.yaml, it ignores other aqua.yaml including global configuration files ($AQUA_GLOBAL_CONFIG).
So if you want to update other files, please change the current directory or specify the configuration file path with the option '-c'.
$ aqua -c foo/aqua.yaml update
If you want to update only registries, please use the --only-registry [-r] option.
# Update only registries
$ aqua update -r
If you want to update only packages, please use the --only-package [-p] option.
# Update only packages
$ aqua update -p
If you want to update only specific packages, please use the -i option.
You can select packages with the fuzzy finder.
If -i option is used, registries aren't updated.
# Select updated packages with fuzzy finder
$ aqua update -i
If you want to select versions, please use the --select-version [-s] option.
You can select versions with the fuzzy finder. You can not only update but also downgrade packages.
By default, -s will only display 30 versions of package.
Use --limit/-l to change it. Non-positive number refers to no limit.
# Select updated packages and versions with fuzzy finder
# Display 30 versions by default
$ aqua update -i -s
# Display only 5 versions
$ aqua update -i -s -l 5
# Display all versions
$ aqua update -i -s -l -1
This command doesn't update packages if the field 'version' is used.
packages:
- name: cli/cli@v2.0.0 # Update
- name: gohugoio/hugo
version: v0.118.0 # Doesn't update
So if you don't want to update specific packages, the field 'version' is useful.
You can specify packages with command names. aqua finds packages that have these commands and updates them.
$ aqua update <command name> [<command name> ...]
e.g.
# Update cli/cli
$ aqua update gh
You can also specify a version.
$ aqua update gh@v2.30.0
You can also filter updated packages using package tags.
e.g.
$ aqua up -t foo # Install only packages having a tag "foo"
$ aqua up --exclude-tags foo # Install only packages not having a tag "foo"
OPTIONS:
-i Select packages with fuzzy finder (default: false)
--select-version, -s Select the version with fuzzy finder. Default to display 30 versions, use --limit/-l to change it. (default: false)
--only-registry, -r Update only registries (default: false)
--only-package, -p Update only packages (default: false)
--limit value, -l value The maximum number of versions. Non-positive number refers to no limit. (default: 30)
--tags value, -t value filter installed packages with tags
--exclude-tags value exclude installed packages with tags
--help, -h show help
aqua completion
$ aqua completion --help
NAME:
aqua completion - Output shell completion script for bash, zsh, or fish
USAGE:
aqua completion command [command options]
DESCRIPTION:
Output shell completion script for bash, zsh, or fish.
Source the output to enable completion.
e.g.
# .bashrc
if command -v aqua &> /dev/null; then
eval "$(aqua completion bash)"
fi
# .zshrc
if command -v aqua &> /dev/null; then
source <(aqua completion zsh)
fi
# fish
aqua completion fish > ~/.config/fish/completions/aqua.fish
aqua completion bash
$ aqua completion bash --help
NAME:
- Output shell completion script for bash
USAGE:
[command options]
OPTIONS:
--help, -h show help
aqua completion zsh
$ aqua completion zsh --help
NAME:
- Output shell completion script for zsh
USAGE:
[command options]
OPTIONS:
--help, -h show help
aqua completion fish
$ aqua completion fish --help
NAME:
- Output shell completion script for fish
USAGE:
[command options]
OPTIONS:
--help, -h show help
aqua which
$ aqua which --help
NAME:
aqua which - Output the absolute file path of the given command
USAGE:
aqua which [command options] <command name>
DESCRIPTION:
Output the absolute file path of the given command
e.g.
$ aqua which gh
/home/foo/.aqua/pkgs/github_release/github.com/cli/cli/v2.4.0/gh_2.4.0_macOS_amd64.tar.gz/gh_2.4.0_macOS_amd64/bin/gh
If the command isn't found in the configuration files, aqua searches the command in the environment variable PATH
$ aqua which ls
/bin/ls
If the command isn't found, exits with non zero exit code.
$ aqua which foo
FATA[0000] aqua failed aqua_version=0.8.6 error="command is not found" exe_name=foo program=aqua
If you want the package version, "--version" option is useful.
$ aqua which --version gh
v2.4.0
OPTIONS:
--version, -v Output the given package version (default: false)
--help, -h show help
aqua info
$ aqua info --help
NAME:
aqua info - Show information
USAGE:
aqua info [command options]
DESCRIPTION:
Show information.
e.g.
$ aqua info
OPTIONS:
--help, -h show help
aqua remove
$ aqua remove --help
NAME:
aqua remove - Uninstall packages
USAGE:
aqua remove [command options] [<registry name>,]<package name> [...]
DESCRIPTION:
Uninstall packages.
e.g.
$ aqua rm --all
$ aqua rm cli/cli direnv/direnv tfcmt # Package names and command names
Note that this command remove files from AQUA_ROOT_DIR/pkgs, but doesn't remove packages from aqua.yaml and doesn't remove files from AQUA_ROOT_DIR/bin and AQUA_ROOT_DIR/bat.
If you want to uninstall packages of non standard registry, you need to specify the registry name too.
e.g.
$ aqua rm foo,suzuki-shunsuke/foo
By default, this command removes only packages from the pkgs directory and doesn't remove links from the bin directory.
You can change this behaviour by specifying the -mode flag.
The value of -mode is a string containing characters "l" and "p".
The order of the characters doesn't matter.
$ aqua rm -m l cli/cli # Remove only links
$ aqua rm -m pl cli/cli # Remove links and packages
Limitation:
"http" and "go_install" packages can't be removed.
OPTIONS:
--all, -a uninstall all packages (default: false)
--mode value, -m value Removed target modes. l: link, p: package [$AQUA_REMOVE_MODE]
-i Select packages with a Fuzzy Finder (default: false)
--help, -h show help
aqua vacuum
$ aqua vacuum --help
NAME:
aqua vacuum - Remove unused installed packages
USAGE:
aqua vacuum [command options]
DESCRIPTION:
Remove unused installed packages.
This command removes unused installed packages, which is useful to save storage and keep your machine clean.
$ aqua vacuum
It removes installed packages which haven't been used for over the expiration days.
The default expiration days is 60, but you can change it by the environment variable $AQUA_VACUUM_DAYS or the command line option "-days <expiration days>".
e.g.
$ export AQUA_VACUUM_DAYS=90
$ aqua vacuum -d 30
As of aqua v2.43.0, aqua records packages' last used date times.
Date times are updated when packages are installed or executed.
Packages installed by aqua v2.42.2 or older don't have records of last used date times, so aqua can't remove them.
To solve the problem, "aqua vacuum --init" is available.
aqua vacuum --init
"aqua vacuum --init" searches installed packages from aqua.yaml including $AQUA_GLOBAL_CONFIG and records the current date time as the last used date time of those packages if their last used date times aren't recorded.
"aqua vacuum --init" can't record date times of install packages which are not found in aqua.yaml.
If you want to record their date times, you need to remove them by "aqua rm" command and re-install them.
OPTIONS:
--init Create timestamp files. (default: false)
--days value, -d value Expiration days (default: 60) [$AQUA_VACUUM_DAYS]
--help, -h show help
aqua cp
$ aqua cp --help
NAME:
aqua cp - Copy executable files in a directory
USAGE:
aqua cp [command options] <command name> [<command name> ...]
DESCRIPTION:
Copy executable files in a directory.
e.g.
$ aqua cp gh
$ ls dist
gh
You can specify the target directory by -o option.
$ aqua cp -o ~/bin terraform hugo
If you don't specify commands, all commands are copied.
$ aqua cp
You can also copy global configuration files' commands with "-a" option.
$ aqua cp -a
You can filter copied commands with package tags.
e.g.
$ aqua cp -t foo # Copy only packages having a tag "foo"
$ aqua cp --exclude-tags foo # Copy only packages not having a tag "foo"
OPTIONS:
-o value destination directory (default: "dist")
--all, -a install all aqua configuration packages (default: false)
--tags value, -t value filter installed packages with tags
--exclude-tags value exclude installed packages with tags
--help, -h show help
aqua policy
$ aqua policy --help
NAME:
aqua policy - Manage Policy
USAGE:
aqua policy command [command options]
aqua policy allow
$ aqua policy allow --help
NAME:
- Allow a policy file
USAGE:
[command options]
DESCRIPTION:
Allow a policy file
e.g.
$ aqua policy allow [<policy file path>]
OPTIONS:
--help, -h show help
aqua policy deny
$ aqua policy deny --help
NAME:
- Deny a policy file
USAGE:
[command options]
DESCRIPTION:
Deny a policy file
e.g.
$ aqua policy deny [<policy file path>]
OPTIONS:
--help, -h show help
aqua policy init
$ aqua policy init --help
NAME:
- Create a policy file if it doesn't exist
USAGE:
[command options] [<created file path. The default value is "aqua-policy.yaml">]
DESCRIPTION:
Create a policy file if it doesn't exist
e.g.
$ aqua policy init # create "aqua-policy.yaml"
$ aqua policy init foo.yaml # create foo.yaml
OPTIONS:
--help, -h show help
aqua init-policy
$ aqua init-policy --help
NAME:
aqua init-policy - [Deprecated] Create a policy file if it doesn't exist
USAGE:
aqua init-policy [command options] [<created file path. The default value is "aqua-policy.yaml">]
DESCRIPTION:
[Deprecated] Create a policy file if it doesn't exist
Please use "aqua policy init" command instead.
e.g.
$ aqua init-policy # create "aqua-policy.yaml"
$ aqua init-policy foo.yaml # create foo.yaml
OPTIONS:
--help, -h show help
aqua exec
$ aqua exec --help
NAME:
aqua exec - Execute tool
USAGE:
aqua exec [command options] <executed command> [<arg> ...]
DESCRIPTION:
Basically you don't have to use this command, because this is used by aqua internally. aqua-proxy invokes this command.
When you execute the command installed by aqua, "aqua exec" is executed internally.
e.g.
$ aqua exec -- gh version
gh version 2.4.0 (2021-12-21)
https://github.com/cli/cli/releases/tag/v2.4.0
OPTIONS:
--help, -h show help
aqua list
$ aqua list --help
NAME:
aqua list - List packages in Registries
USAGE:
aqua list [command options]
DESCRIPTION:
Output the list of packages in registries.
The output format is <registry name>,<package name>
e.g.
$ aqua list
standard,99designs/aws-vault
standard,abiosoft/colima
standard,abs-lang/abs
...
If the option -installed is set, the command lists only installed packages.
$ aqua list -installed
standard,golangci/golangci-lint,v1.56.2
standard,goreleaser/goreleaser,v1.24.0
...
By default, the command doesn't list global configuration packages.
If you want to list global configuration packages too, please set the option -a.
$ aqua list -installed -a
OPTIONS:
--installed, -i List installed packages (default: false)
--all, -a List global configuration packages too (default: false)
--help, -h show help
aqua generate-registry
$ aqua generate-registry --help
NAME:
aqua generate-registry - Generate a registry's package configuration
USAGE:
aqua generate-registry [command options] <package name>
DESCRIPTION:
Generate a template of Registry package configuration.
Note that you probably fix the generate code manually.
The generate code is not perfect and may include the wrong configuration.
It is just a template.
e.g.
$ aqua gr cli/cli # Outputs the configuration.
packages:
- type: github_release
repo_owner: cli
repo_name: cli
asset: gh_{{trimV .Version}}_{{.OS}}_{{.Arch}}.{{.Format}}
format: tar.gz
description: GitHub’s official command line tool
replacements:
darwin: macOS
overrides:
- goos: windows
format: zip
supported_envs:
- darwin
- linux
- amd64
rosetta2: true
By default, aqua gets the information from the latest GitHub Releases.
You can specify a specific package version.
e.g.
$ aqua gr cli/cli@v2.0.0
By default, aqua gr gets all GitHub Releases to generate version_overrides.
You can limit the number of GitHub Releases by --limit.
e.g.
$ aqua gr --limit 100 suzuki-shunsuke/tfcmt
If --out-testdata is set, aqua inserts testdata into the specified file.
e.g.
$ aqua gr --out-testdata testdata.yaml suzuki-shunsuke/tfcmt
If -cmd is set, aqua sets files.
e.g.
$ aqua gr -cmd gh cli/cli
files:
- name: gh
You can specify multiple commands with commas ",".
e.g.
$ aqua gr -cmd age,age-keygen FiloSottile/age
files:
- name: age
- name: age-keygen
OPTIONS:
--out-testdata value A file path where the testdata is outputted
--cmd value A list of commands joined with commas ','
--limit value, -l value the maximum number of versions (default: 0)
--deep This flag was deprecated and had no meaning from aqua v2.15.0. This flag will be removed in aqua v3.0.0. https://github.com/aquaproj/aqua/issues/2351 (default: false)
--help, -h show help
aqua version
$ aqua version --help
NAME:
aqua version - Show version
USAGE:
aqua version [command options]
OPTIONS:
--help, -h show help
aqua root-dir
$ aqua root-dir --help
NAME:
aqua root-dir - Output the aqua root directory (AQUA_ROOT_DIR)
USAGE:
aqua root-dir [command options]
DESCRIPTION:
Output the aqua root directory (AQUA_ROOT_DIR)
e.g.
$ aqua root-dir
/home/foo/.local/share/aquaproj-aqua
$ export "PATH=$(aqua root-dir)/bin:PATH"
OPTIONS:
--help, -h show help