Aqua CLI Configuration Options: A Complete Guide to Global and Command-Specific Flags

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 and wired through cmd/aqua/main.go.

--config <string> or -c <string> overrides the default search algorithm to specify a custom path to aqua.yaml.

--log-level <string> 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 <string> to write execution traces to a file and --cpu-profile <string> 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, install.go, 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 using an import_dir structure instead of a flat packages: list
• --import-dir <string> or -i <string> specifies the target directory for imports
• --create-dir or -d creates an aqua/ subdirectory and places the configuration at 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 <string> or -t <string> filters installation to packages matching specific tags
• --exclude-tags <string> omits packages with the specified tags

aqua generate Options

The generate command (aliased as g) configures how package entries are created:

• -f <string> 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 instead of the nearest local file
• --detail or -d includes description and link fields in the output
• -o <string> writes output to a specific file instead of stdout
• --select-version or -s launches an interactive version selector, with --limit or -l <int> 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 <int> or -l <int> limits displayed versions when using -s
• --tags <string> or -t <string> and --exclude-tags <string> 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 <string> or -m <string> 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 <int> or -d <int> sets the expiration threshold (default 60 days)

aqua cp copies executables:

• -o <string> 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 <string> for writing test data files
• --cmd <string> for comma-separated command lists
• --limit <int> or -l <int> 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 serves as the central markdown defining CLI help text for both global and command options
• 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, install.go, update.go) that register specific flags
• 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:

aqua --help

Use a custom configuration file with debug logging:

aqua -c ./my-aqua.yaml --log-level debug list -a

Initialize a new project with import directory support:

aqua init -u -i imports

Install only CI-tagged packages:

aqua i -t ci

Generate a pinned package entry for GitHub CLI:

aqua g cli/cli --pin > aqua.yaml

Update only registry definitions without touching package versions:

aqua update -r

Remove only symlinks while preserving cached binaries:

aqua rm -m l gh

Vacuum packages unused for 90 days:

AQUA_VACUUM_DAYS=90 aqua vacuum

Generate a registry configuration for a specific tool:

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 for documentation and 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 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 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 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 in the current directory tree.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}