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

> Explore aqua CLI commands like init install generate and update to manage declarative package installations efficiently. Get the complete guide to aquaproj/aqua tool.

- Repository: [aquaproj/aqua](https://github.com/aquaproj/aqua)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/initcmd/command.go)

```bash
aqua init

```

### install - Install Defined Tools

The `install` command (alias `i`) downloads, extracts, and creates symlinks for all tools defined in [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/install/command.go)

```bash

# 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`](https://github.com/aquaproj/aqua/blob/main/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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/generate/command.go)

```bash
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)](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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/updateaqua/command.go)

```bash

# 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)](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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/vacuum/command.go)

```bash

# 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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/which/command.go)

```bash

# 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)](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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/list/command.go)

```bash

# 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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/root/command.go)

```bash
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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/remove/command.go)

```bash

# 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)](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)](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)](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)](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)](https://github.com/aquaproj/aqua/blob/main/pkg/cli/genr/command.go)

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

```

## Command Architecture

All **aqua CLI commands** are wired together in [`pkg/cli/runner.go`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/pkg/cli/cliargs/cliargs.go). The actual business logic for each command delegates to controllers in `pkg/controller/`, while [`cmd/aqua/main.go`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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.