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

> Learn to configure aqua.yaml for custom commands using command aliases. Aqua creates symbolic links so you can invoke aliases like native commands easily.

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

---

**Aqua lets you expose additional command names for a package through command aliases defined in the `command_aliases` field of [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`:

```yaml
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:

```bash
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.

```yaml
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:

```bash
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.

```yaml
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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/pkg/config/aqua/config.go) | Defines `Package.CommandAliases` and `CommandAlias` structs |
| [`website/docs/guides/command-alias.md`](https://github.com/aquaproj/aqua/blob/main/website/docs/guides/command-alias.md) | User-facing documentation with examples |
| [`website/docs/reference/config/index.md`](https://github.com/aquaproj/aqua/blob/main/website/docs/reference/config/index.md) | Schema reference for `command_aliases` |

## Summary

- **Command aliases** in [`aqua.yaml`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/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`](https://github.com/aquaproj/aqua/blob/main/aqua.yaml) file.