usage.md

---
sidebar_position: 400
---

# Usage

<!-- This is generated by scripts/generate-usage.sh. Don't edit this file directly. -->

```console
$ aqua help
NAME:
   aqua - Version Manager of CLI. https://aquaproj.github.io/

USAGE:
   aqua [global options] command [command options] 

VERSION:
   2.29.0 (9ff65378f0c6197e3130a20f6d978b8a3042b463)

COMMANDS:
   init                   Create a configuration file if it doesn't exist
   info                   Show information
   init-policy            [Deprecated] Create a policy file if it doesn't exist
   policy                 Manage Policy
   install, i             Install tools
   update-aqua, upa       Update aqua
   generate, g            Search packages in registries and output the configuration interactively
   which                  Output the absolute file path of the given command
   exec                   Execute tool
   list                   List packages in Registries
   generate-registry, gr  Generate a registry's package configuration
   completion             Output shell completion script for bash, zsh, or fish
   version                Show version
   cp                     Copy executable files in a directory
   root-dir               Output the aqua root directory (AQUA_ROOT_DIR)
   update-checksum, upc   Create or Update aqua-checksums.json
   remove, rm             Uninstall packages
   update, up             Update registries and packages
   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]
   --trace value             trace output file path
   --cpu-profile value       cpu profile output file path
   --help, -h                show help
   --version, -v             print the version
```

## aqua install

```console
$ aqua help install
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

```console
$ aqua help generate
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 init

```console
$ aqua help init
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

OPTIONS:
   --help, -h  show help
```

## aqua update-aqua

```console
$ aqua help update-aqua
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

```console
$ aqua help update-checksum
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 which

```console
$ aqua help which
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 remove

```console
$ aqua help remove
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

   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.

   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

   Limitation:
   "http" and "go_install" packages can't be removed.


OPTIONS:
   --all, -a   uninstall all packages (default: false)
   -i          Select packages with a Fuzzy Finder (default: false)
   --help, -h  show help
```

## aqua cp

```console
$ aqua help cp
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 info

```console
$ aqua help info
NAME:
   aqua info - Show information

USAGE:
   aqua info [command options]

DESCRIPTION:
   Show information.
   e.g.
   $ aqua info

OPTIONS:
   --help, -h  show help
```

## aqua generate-registry

```console
$ aqua help generate-registry
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 list

```console
$ aqua help list
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  List installed packages (default: false)
   --all, -a    List global configuration packages too (default: false)
   --help, -h   show help
```

## aqua completion

```console
$ aqua help completion
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 exec

```console
$ aqua help exec
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
```