# Aqua CLI Configuration Options: A Complete Guide to Global and Command-Specific Flags > Master Aqua CLI configuration. Explore global flags like --config and --log-level, plus command-specific options for init, install, and more. Optimize your workflow today. - Repository: [aquaproj/aqua](https://github.com/aquaproj/aqua) - Tags: how-to-guide - Published: 2026-02-25 --- **Aqua CLI configuration options include global flags like `--config`, `--log-level`, and security verification toggles, plus command-specific options for `init`, `install`, `generate`, `update`, and other subcommands.** The **aqua** CLI from the `aquaproj/aqua` repository uses a dual-layer configuration system. Global flags control universal behaviors such as logging and security verification, while command-specific options fine-tune individual operations like package installation and registry generation. Understanding these aqua CLI configuration options allows you to customize the tool's behavior for both local development and CI/CD pipelines. ## Global Configuration Options Global flags apply to every subcommand in the aqua CLI. These options are defined in [`website/docs/reference/usage.md`](https://github.com/aquaproj/aqua/blob/main/website/docs/reference/usage.md) and wired through [`cmd/aqua/main.go`](https://github.com/aquaproj/aqua/blob/main/cmd/aqua/main.go). **`--config ` or `-c `** overrides the default search algorithm to specify a custom path to [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml). **`--log-level `** controls verbosity, accepting values like `debug`, `info`, or `error`. **Security verification toggles** allow you to disable specific attestation checks: - `--disable-cosign` turns off Cosign signature verification - `--disable-slsa` disables SLSA provenance verification - `--disable-github-artifact-attestation` skips GitHub Artifact Attestation verification - `--disable-github-immutable-release` bypasses immutable GitHub Release attestation checks **Debugging flags** include `--trace ` to write execution traces to a file and `--cpu-profile ` to generate pprof-compatible CPU profiles. Standard help and version flags (`-h`, `--help`, `-v`, `--version`) are also available globally. ## Command-Specific Configuration Options Each subcommand registers its own flags in the `pkg/cli/` directory (e.g., [`init.go`](https://github.com/aquaproj/aqua/blob/main/init.go), [`install.go`](https://github.com/aquaproj/aqua/blob/main/install.go), [`update.go`](https://github.com/aquaproj/aqua/blob/main/update.go)). These options refine behavior for specific workflows. ### aqua init Options When bootstrapping a new configuration, the `init` command supports: - `--use-import-dir` or `-u` creates [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) using an `import_dir` structure instead of a flat `packages:` list - `--import-dir ` or `-i ` specifies the target directory for imports - `--create-dir` or `-d` creates an `aqua/` subdirectory and places the configuration at [`aqua/aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua/aqua.yaml) ### aqua install Options The `install` command (aliased as `i`) provides filtering and linking controls: - `--only-link` or `-l` creates symlinks only, skipping binary downloads - `--all` or `-a` installs packages from both local and global configurations - `--tags ` or `-t ` filters installation to packages matching specific tags - `--exclude-tags ` omits packages with the specified tags ### aqua generate Options The `generate` command (aliased as `g`) configures how package entries are created: - `-f ` reads package lists from a file (use `-` for stdin) - `-i` inserts generated packages directly into the configuration file - `--pin` pins versions to prevent Renovate from upgrading them automatically - `-g` targets the global [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) instead of the nearest local file - `--detail` or `-d` includes description and link fields in the output - `-o ` writes output to a specific file instead of stdout - `--select-version` or `-s` launches an interactive version selector, with `--limit` or `-l ` controlling the number of displayed versions (default 30) ### aqua update Options The `update` command (aliased as `up`) manages version and registry refreshes: - `-i` opens a fuzzy finder to select specific packages for updating - `--select-version` or `-s` enables interactive version selection - `--only-registry` or `-r` updates only registry definitions - `--only-package` or `-p` updates only package versions - `--limit ` or `-l ` limits displayed versions when using `-s` - `--tags ` or `-t ` and `--exclude-tags ` filter the update set by tags ### Other Command Options **`aqua which`** supports `--version` or `-v` to display the resolved package version instead of the file path. **`aqua remove`** (aliased as `rm`) accepts: - `--all` or `-a` to uninstall all packages - `--mode ` or `-m ` with values `l` (links), `p` (packages), or `pl` (both) to control deletion scope - `-i` to use a fuzzy finder for package selection **`aqua vacuum`** cleans unused packages: - `--init` initializes timestamp files for all configured packages - `--days ` or `-d ` sets the expiration threshold (default 60 days) **`aqua cp`** copies executables: - `-o ` specifies the destination directory (default `dist`) - `--all` or `-a` includes global configuration packages - `--tags` and `--exclude-tags` filter which packages to copy **`aqua generate-registry`** (aliased as `gr`) supports: - `--out-testdata ` for writing test data files - `--cmd ` for comma-separated command lists - `--limit ` or `-l ` for maximum releases to fetch - `--init` to write a new configuration file instead of stdout output **`aqua token`** provides `set` and `remove` subcommands for GitHub token management in the OS keyring. **`aqua policy`** manages policy files through `allow`, `deny`, and `init` subcommands. ## Source Code Implementation The aqua CLI configuration options are implemented across several key files in the `aquaproj/aqua` repository: - [`website/docs/reference/usage.md`](https://github.com/aquaproj/aqua/blob/main/website/docs/reference/usage.md) serves as the central markdown defining CLI help text for both global and command options - [`cmd/aqua/main.go`](https://github.com/aquaproj/aqua/blob/main/cmd/aqua/main.go) implements the urfave/cli command tree where flags are wired to handlers - `pkg/cli/` contains individual command implementations (e.g., [`init.go`](https://github.com/aquaproj/aqua/blob/main/init.go), [`install.go`](https://github.com/aquaproj/aqua/blob/main/install.go), [`update.go`](https://github.com/aquaproj/aqua/blob/main/update.go)) that register specific flags - [`pkg/config/reader.go`](https://github.com/aquaproj/aqua/blob/main/pkg/config/reader.go) handles reading the configuration file referenced by `--config` - `pkg/policy/` manages the `policy` subcommands (`allow`, `deny`, `init`) ## Practical Configuration Examples Show global help and available commands: ```bash aqua --help ``` Use a custom configuration file with debug logging: ```bash aqua -c ./my-aqua.yaml --log-level debug list -a ``` Initialize a new project with import directory support: ```bash aqua init -u -i imports ``` Install only CI-tagged packages: ```bash aqua i -t ci ``` Generate a pinned package entry for GitHub CLI: ```bash aqua g cli/cli --pin > aqua.yaml ``` Update only registry definitions without touching package versions: ```bash aqua update -r ``` Remove only symlinks while preserving cached binaries: ```bash aqua rm -m l gh ``` Vacuum packages unused for 90 days: ```bash AQUA_VACUUM_DAYS=90 aqua vacuum ``` Generate a registry configuration for a specific tool: ```bash aqua gr -o tfcmt.yaml suzuki-shunsuke/tfcmt ``` ## Summary - **Global flags** like `--config`, `--log-level`, and security toggles (`--disable-cosign`, `--disable-slsa`) apply to all aqua CLI operations - **Command-specific options** allow fine-grained control over `init`, `install`, `generate`, `update`, and maintenance commands like `vacuum` and `remove` - **Configuration discovery** follows a default search algorithm unless overridden by `-c`, with global configuration accessible via `-g` on relevant commands - **Security verification** can be selectively disabled via global flags, though this reduces supply-chain security guarantees - **Source files** defining these options include [`website/docs/reference/usage.md`](https://github.com/aquaproj/aqua/blob/main/website/docs/reference/usage.md) for documentation and [`cmd/aqua/main.go`](https://github.com/aquaproj/aqua/blob/main/cmd/aqua/main.go) combined with `pkg/cli/*.go` for implementation ## Frequently Asked Questions ### How do I specify a custom configuration file path for aqua commands? Use the global `--config` or `-c` flag followed by the file path. For example: `aqua -c ./configs/aqua.yaml install`. This overrides the default search algorithm that looks for [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) in the current directory and parent directories. ### What is the difference between the `--tags` and `--exclude-tags` flags in aqua install? The `--tags` or `-t` flag filters the installation to include only packages matching the specified tags, while `--exclude-tags` omits packages that have the specified tag. These flags are available in `install`, `update`, and `cp` commands to control which subset of your defined packages get processed. ### How can I disable signature verification when installing packages with aqua? Pass the global `--disable-cosign` flag to skip Cosign signature verification, `--disable-slsa` to skip SLSA provenance verification, or `--disable-github-artifact-attestation` to skip GitHub Artifact Attestation checks. These flags are defined in the global options section of [`website/docs/reference/usage.md`](https://github.com/aquaproj/aqua/blob/main/website/docs/reference/usage.md) and processed before any package download begins. ### Where does aqua store its configuration when using the `-g` flag? The `-g` or `--global` flag targets the global [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) file, typically located in the aqua root directory (often `~/.local/share/aquaproj-aqua/` or the directory specified by the `AQUA_ROOT_DIR` environment variable). This differs from the default behavior which searches for the nearest local [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) in the current directory tree.