Complete Guide to Aqua CLI Commands in the aquaproj/aqua Tool

The aqua CLI provides 17 distinct commands—including init, install, generate, update, and remove—that manage declarative package installations, with all command logic centralized in pkg/cli/runner.go and implemented via the urfave/cli v3 framework.

The aqua CLI is a declarative CLI version manager built by the aquaproj/aqua repository that uses YAML configuration to install and manage development tools. Built on the urfave/cli v3 framework, the binary exposes its command surface through a hierarchical structure defined in pkg/cli/runner.go, where each sub-command resides in its own dedicated package under pkg/cli/.

Core Package Management Commands

These commands form the essential workflow for initializing projects and installing tools.

init - Initialize Configuration

The init command creates a new aqua configuration file (aqua.yaml) and the .aqua directory structure. This is the entry point for new projects adopting aqua for dependency management.

Source: [pkg/cli/initcmd/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/initcmd/command.go)

aqua init

install - Install Defined Tools

The install command (alias i) downloads, extracts, and creates symlinks for all tools defined in aqua.yaml. It supports selective installation modes to control whether binaries are downloaded or only symlinks are created.

Source: [pkg/cli/install/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/install/command.go)

# Install everything defined in aqua.yaml

aqua install

# or

aqua i

# Install only symbolic links, skip downloading binaries

aqua install --only-link

# or

aqua i -l

generate - Interactive Configuration Generator

The generate command (alias g) launches an interactive fuzzy-finder to search registries and emit configuration snippets for aqua.yaml. This eliminates manual lookup of package names and versions.

Source: [pkg/cli/generate/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/generate/command.go)

aqua generate cli/cli

Update and Maintenance Commands

These commands handle version updates, binary self-updates, and system hygiene.

update - Upgrade Installed Packages

The update command refreshes installed packages to their latest versions while respecting any version constraints defined in the configuration.

Source: [pkg/cli/update/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/update/command.go)

update-aqua - Self-Update the Binary

The update-aqua command (alias upa) handles self-updates of the aqua binary itself, either to the latest release or a specific version tag.

Source: [pkg/cli/updateaqua/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/updateaqua/command.go)

# Update to latest

aqua update-aqua

# Update to specific version

aqua update-aqua v1.21.0

update-checksum - Refresh Checksum Files

The update-checksum command (alias upc) rewrites the checksum file for packages, typically used after manual edits to package configurations to ensure integrity validation remains accurate.

Source: [pkg/cli/upc/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/upc/command.go)

vacuum - Clean Unused Packages

The vacuum command removes unused packages based on last-used timestamps, reclaiming disk space from tools that haven't been executed recently.

Source: [pkg/cli/vacuum/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/vacuum/command.go)

# Clean up packages unused for 30 days

aqua vacuum --days 30

Inspection and Query Commands

These commands provide visibility into the installed toolset and available packages.

which - Locate Executables

The which command prints the absolute path of a managed executable or its version information. This resolves the actual location of tools installed by aqua.

Source: [pkg/cli/which/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/which/command.go)

# Show full path

aqua which gh

# Show only version

aqua which --version gh

info - Display Package Metadata

The info command shows detailed metadata for a package, including its registry source, installed version, and available assets.

Source: [pkg/cli/info/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/info/command.go)

list - Browse Available Packages

The list command enumerates packages available in configured registries. It supports filtering to show only currently installed packages.

Source: [pkg/cli/list/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/list/command.go)

# List all packages in registries

aqua list

# List only installed packages

aqua list --installed

# or

aqua list -i

root-dir - Show Installation Path

The root-dir command prints the Aqua root directory (AQUA_ROOT_DIR), revealing where all packages and metadata are stored on the filesystem.

Source: [pkg/cli/root/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/root/command.go)

aqua root-dir

Package Removal Commands

remove - Uninstall Packages

The remove command (alias rm) uninstalls packages with flexible modes: it can remove both package files and symlinks, or preserve files while removing only symlinks.

Source: [pkg/cli/remove/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/remove/command.go)

# Remove package and symlink

aqua remove cli/cli

# Remove only symlink, keep package files

aqua remove --mode l cli/cli

Advanced Utility Commands

cp - Copy Package Files

The cp command copies installed package files to a destination directory, useful for creating isolated tool bundles or offline distributions.

Source: [pkg/cli/cp/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/cp/command.go)

exec - Run in Aqua Environment

The exec command executes a command inside the aqua environment, automatically adding installed binaries to $PATH for the duration of the command.

Source: [pkg/cli/exec/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/exec/command.go)

token - Manage GitHub Authentication

The token command manages GitHub token storage via the system keyring, supporting set, get, and delete operations for authenticated API access.

Source: [pkg/cli/token/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/token/command.go)

policy - Security Policy Management

The policy command provides sub-commands for managing security policies: allow, deny, and init-policy. These control which packages or registries are permitted in the environment.

Source: [pkg/cli/policy/policy.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/policy/policy.go)

Registry Development Commands

generate-registry - Create Registry Entries

The generate-registry command (alias gr) generates a template registry entry for a new package, outputting YAML suitable for contribution to aqua registries.

Source: [pkg/cli/genr/command.go](https://github.com/aquaproj/aqua/blob/main/pkg/cli/genr/command.go)

aqua generate-registry cli/cli > aqua-registry.yaml

Command Architecture

All aqua CLI commands are wired together in pkg/cli/runner.go within the commands slice. Each command implements a constructor function New(r *util.Param, globalArgs *cliargs.GlobalArgs) *cli.Command that returns a urfave/cli/v3 command object.

Global flags shared across all commands—such as log level and configuration path—are defined in pkg/cli/cliargs/cliargs.go. The actual business logic for each command delegates to controllers in pkg/controller/, while cmd/aqua/main.go serves as the minimal entry point that invokes cli.Runner.Run.

Summary

• The aqua CLI exposes 17 primary commands through the urfave/cli/v3 framework, centralized in pkg/cli/runner.go.
• Core workflow commands include init, install (i), and generate (g) for setup and configuration.
• Maintenance commands cover update, update-aqua (upa), update-checksum (upc), remove (rm), and vacuum for lifecycle management.
• Query commands such as which, info, list, and root-dir provide visibility into the toolset.
• Advanced utilities include cp, exec, token, and policy for specialized operations and security management.
• Registry development is supported via generate-registry (gr).

Frequently Asked Questions

What is the aqua CLI used for?

The aqua CLI is a declarative package manager that installs and manages command-line tools via YAML configuration files. It handles binary downloads, checksum verification, and symlink creation in a centralized directory, allowing version pinning and reproducible environments across teams.

How do I update the aqua binary itself?

Use the update-aqua command (alias upa). Run aqua update-aqua to fetch the latest release, or specify a version like aqua update-aqua v1.21.0 to pin to a specific release. This command is implemented in pkg/cli/updateaqua/command.go.

What is the difference between aqua remove and aqua vacuum?

The remove command (rm) immediately uninstalls specific packages by name, with options to delete only symlinks (--mode l) or both files and symlinks. The vacuum command operates on time-based criteria, removing packages that haven't been executed for a specified number of days regardless of name, effectively garbage-collecting unused tools.

How does the aqua install command handle symlinks?

By default, aqua install (alias i) downloads binaries and creates symlinks in $(aqua root-dir)/bin. The --only-link (or -l) flag skips downloading and extracts existing packages, recreating only the symlinks—useful when migrating configurations or repairing PATH entries without re-downloading assets.

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