How to Update Tools with the aqua update Command: A Complete Guide

Use aqua update to automatically refresh the versions of tools declared in your aqua.yaml file, with options to target specific packages, use interactive selection, or limit updates to registries only.

The aqua update command is the primary mechanism for keeping your development tools current in the aquaproj/aqua ecosystem. Whether you are managing a single project or an organization-wide toolchain, understanding how to update tools with the aqua update command ensures your dependencies remain secure and feature-rich without manual version hunting.

How aqua update Works

The update process operates through three distinct phases defined in pkg/controller/update/update.go.

Configuration Discovery

The controller first locates your configuration file using the config-finder component. It searches for aqua.yaml starting from the current working directory, or uses the path specified with the -c flag. If no configuration file is found, the process returns finder.ErrConfigFileNotFound and exits【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L24-L30】.

Reading Configuration and Checksum Data

Once located, the configuration file is unmarshaled into the aqua.Config struct defined in pkg/config/aqua/config.go. If checksum verification is enabled (param.ChecksumEnabled), the controller opens the aqua-checksums.json file using the checksum package to validate existing installations【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L82-L88】.

Registry and Package Updates

The actual update occurs in two sequential steps:

1. Registry Installation: Unless the --only-package flag is set, the controller calls registryInstaller.InstallRegistries to ensure the latest registry definitions are present before querying package versions【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L92-L99】.

2. Package Refresh: The c.updatePackages method queries remote sources (GitHub Releases, Git tags, crates.io) for the latest versions and writes the updated version strings back into aqua.yaml【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L92-L99】.

Command-Line Flags and Options

The aqua update command respects a rich set of flags that shape the update workflow:

• -r, --only-registry: Skip package updates and refresh only the registries.
• -p, --only-package: Skip registry updates and refresh only the packages.
• -i: Launch a fuzzy-finder UI to interactively select which packages to upgrade.
• -s, --select-version: After picking packages with -i, also pick the target version (defaults to showing the latest 30).
• -l <n>: Change the number of versions shown by the picker (-1 = unlimited).
• -t <tag> / --exclude-tags <tag>: Filter packages by user-defined tags.
• -c <path>: Explicitly point to a configuration file other than the nearest aqua.yaml.

Important: aqua update only rewrites version fields in the configuration. It does not modify commit hashes. If a package has a pinned version: entry, it remains untouched according to the source code documentation【/cache/repos/github.com/aquaproj/aqua/main/website/docs/reference/usage.md#L81-L88】.

Practical Usage Examples

Here are concrete commands for common update scenarios:

# Update all registries and packages to the latest versions

aqua update

# Update only the registries (skip packages)

aqua update -r

# Update only the packages (keep current registries)

aqua update -p

# Interactive selection of packages to upgrade

aqua update -i

# Interactive selection of packages AND target versions

aqua update -i -s

# Show all available versions for the interactive picker

aqua update -i -s -l -1

# Update a specific tool by its command name

aqua update gh

# Upgrade a tool to a specific version

aqua update gh@v2.30.0

# Use a custom configuration file

aqua -c path/to/custom/aqua.yaml update

Internal Implementation Details

When you specify a package name or command name (e.g., aqua update gh), the controller resolves the command to a package using the which component【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L45-L50】.

If you provide an explicit version constraint like gh@v2.30.0, that version is recorded directly. Otherwise, c.getPackageNewVersion queries the upstream source (GitHub Releases, tags, or crates.io) for the latest release and returns the version string. The controller then writes this back to the configuration file using c.updateFile【/cache/repos/github.com/aquaproj/aqua/main/pkg/controller/update/update.go#L55-L62】.

Summary

• aqua update automates version management by scanning aqua.yaml, querying remote sources, and writing back the latest versions.
• The command operates in three phases: configuration discovery, checksum validation, and registry/package updates.
• Use flags like -r, -p, -i, and -s to control whether you update registries, packages, or use interactive selection.
• The implementation in pkg/controller/update/update.go handles command resolution via the which component and version querying through getPackageNewVersion.

Frequently Asked Questions

Does aqua update modify commit hashes or only version strings?

aqua update only modifies the version fields in your aqua.yaml configuration. It does not rewrite commit hashes. If a package entry already has a pinned version: field, the command leaves it untouched to prevent accidental overrides of explicit version constraints.

Can I update a specific tool without affecting others?

Yes. You can pass the command name or package name as an argument to update a single tool. For example, aqua update gh updates only the package providing the gh command. You can also use the -i flag to launch an interactive fuzzy-finder and select specific packages from a list.

What is the difference between updating registries and updating packages?

Registries contain the metadata and installation logic for tools, while packages are the actual tool versions you use. The -r (--only-registry) flag updates only the registry definitions, ensuring you have the latest package schemas. The -p (--only-package) flag skips registry updates and only refreshes the tool versions in your configuration. By default, aqua update performs both operations sequentially.

How does aqua update handle configuration files in subdirectories?

The command uses the config-finder component to locate the nearest aqua.yaml starting from the current working directory and walking up the directory tree. If you need to target a specific configuration file outside this search path, use the -c flag followed by the absolute or relative path to the file.

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