How to Configure aqua.yaml for Custom Commands: A Complete Guide to Command Aliases

Aqua lets you expose additional command names for a package through command aliases defined in the command_aliases field of aqua.yaml, creating symbolic links to the original executable so aliases can be invoked like native commands.

When managing multiple versions of CLI tools with aquaproj/aqua, you often need to invoke different versions side-by-side or use shorter command names. Learning how to configure aqua.yaml for custom commands through the command_aliases feature allows you to define alternative names for any package executable. This configuration creates symbolic links by default, making aliases behave exactly like the original commands in your shell.

Understanding Command Aliases in aqua.yaml

What Are Command Aliases?

Command aliases in Aqua are alternative names assigned to package executables. When you install a package with aliases, Aqua creates symbolic links (by default) from the alias name to the original binary. This allows you to run the same tool using different command names, which is particularly useful for managing multiple versions of the same tool simultaneously.

The Configuration Schema

According to the aquaproj/aqua source code, aliases are defined in the Package struct located in pkg/config/aqua/config.go. The relevant fields include:

• CommandAliases []*CommandAlias — a slice containing all alias definitions for the package
• CommandAlias struct fields:
  • Command — the original executable name
  • Alias — the new command name
  • NoLink — boolean to prevent symlink creation

How to Configure aqua.yaml for Custom Commands

Basic Alias Configuration

To create a simple alias that generates a symbolic link, add a command_aliases list to your package entry. Each alias requires the command (original name) and alias (new name) fields.

The following example installs two versions of Terraform side-by-side, exposing the older version as terraform-013:

registries:
- type: standard
  ref: v4.246.0 # renovate: depName=aquaproj/aqua-registry

packages:
- name: hashicorp/terraform@v1.9.8          # default command name: terraform

- name: hashicorp/terraform
  version: v0.13.7
  command_aliases:
    - command: terraform                    # original command

      alias: terraform-013                 # new command name

After running aqua install, both commands are available in your shell:

terraform version        # → v1.9.8

terraform-013 version    # → v0.13.7

Running Aliases Without Symlinks

If you prefer not to create symbolic links in your binary directory, set no_link: true in the alias definition. This is useful when you want to avoid polluting your PATH or when the alias is only needed occasionally.

packages:
- name: hashicorp/terraform
  version: v0.13.7
  command_aliases:
    - command: terraform
      alias: terraform-013
      no_link: true

With this configuration, the alias is not linked into $HOME/.local/bin. Instead, invoke it explicitly through Aqua:

aqua exec -- terraform-013 version

Multiple Aliases for the Same Package

You can define multiple aliases for different executables within the same package. This is common with Node.js, where you might want to expose both node and npm with version-specific names.

packages:
- name: nodejs/node
  version: v18.20.0
  command_aliases:
    - command: node
      alias: node18
    - command: npm
      alias: npm18

Now node18 and npm18 invoke the Node v18 binaries, allowing you to work with multiple Node versions simultaneously without switching environments.

Implementation Details in Aqua

The command aliases feature was introduced in Aqua v2.37.0. The implementation centers on the configuration parsing logic in pkg/config/aqua/config.go, where the Package struct includes a CommandAliases field of type []*CommandAlias. Each CommandAlias struct contains:

• Command string — the original binary name
• Alias string — the custom command name
• NoLink bool — whether to skip symlink creation

During installation, Aqua processes these aliases to create symbolic links in your configured binary directory (unless NoLink is true), enabling the custom commands to function as first-class shell commands.

Key source files for reference:

File	Purpose
pkg/config/aqua/config.go	Defines Package.CommandAliases and CommandAlias structs
website/docs/guides/command-alias.md	User-facing documentation with examples
website/docs/reference/config/index.md	Schema reference for command_aliases

Summary

• Command aliases in aqua.yaml let you expose custom command names for any package executable through the command_aliases field.
• Each alias requires a command (original name) and alias (custom name), with an optional no_link property to prevent symlink creation.
• Aliases enable side-by-side installation of multiple tool versions, such as running Terraform 1.9.8 as terraform and Terraform 0.13.7 as terraform-013.
• When no_link: true is set, execute aliases via aqua exec -- <alias> instead of direct shell invocation.
• The feature is implemented in pkg/config/aqua/config.go and available since Aqua v2.37.0.

Frequently Asked Questions

What version of Aqua supports command aliases?

Command aliases were introduced in Aqua v2.37.0. You must upgrade to this version or later to use the command_aliases field in your aqua.yaml configuration.

How do I run an alias without a symlink?

If you set no_link: true in your alias definition, Aqua does not create a symbolic link in your binary directory. Instead, run the command using aqua exec -- <alias> [arguments]. This approach keeps your PATH clean while still allowing access to the tool.

Can I create multiple aliases for the same package?

Yes. The command_aliases field accepts a list of alias definitions. You can define multiple aliases for different executables within the same package, such as aliasing both node and npm from the Node.js package to node18 and npm18 respectively.

Where is the alias configuration defined in the source code?

The alias configuration is defined in pkg/config/aqua/config.go. The Package struct contains a CommandAliases field of type []*CommandAlias, where each CommandAlias struct specifies the Command, Alias, and NoLink properties parsed from your aqua.yaml file.

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