Skip to main content

Toolchain Aliases

Tool aliases provide convenient shorthand names for tools, allowing you to use simple names like terraform instead of the full registry path hashicorp/terraform.

Aliases also provide the tool target for toolchain proxies, such as mapping coreutils to uutils/coreutils before exposing an ls command.

You will learn

  • Define short names for frequently used tools
  • Multiple aliases can point to the same tool
  • Aliases are resolved before registry lookups
  • Works with all registry types (Aqua, inline, custom)
  • Use aliases with any toolchain command

Basic Configuration​

Define aliases in your atmos.yaml:

atmos.yaml
toolchain:
  aliases:
    # HashiCorp tools
    terraform: hashicorp/terraform
    tf: hashicorp/terraform        # Multiple aliases → same tool
    packer: hashicorp/packer
    vault: hashicorp/vault
    consul: hashicorp/consul

    # OpenTofu
    opentofu: opentofu/opentofu
    tofu: opentofu/opentofu

    # Kubernetes tools
    kubectl: kubernetes-sigs/kubectl
    helm: helm/helm
    k9s: derailed/k9s

    # AWS tools
    aws: aws/aws-cli
    awscli: aws/aws-cli

How Aliases Work​

Aliases are resolved before registry lookups:

  1. User runs: atmos toolchain install terraform@1.9.8
  2. Atmos checks aliases: terraform → hashicorp/terraform
  3. Atmos searches registries for hashicorp/terraform
  4. Tool is installed

Without aliases, you would need to use the full path:

# Without alias
atmos toolchain install hashicorp/terraform@1.9.8

# With alias
atmos toolchain install terraform@1.9.8

Multiple Aliases​

Multiple aliases can point to the same tool:

atmos.yaml
toolchain:
  aliases:
    terraform: hashicorp/terraform
    tf: hashicorp/terraform         # Shorthand
    hc-terraform: hashicorp/terraform  # Explicit

All these commands install the same tool:

atmos toolchain install terraform@1.9.8
atmos toolchain install tf@1.9.8
atmos toolchain install hc-terraform@1.9.8

Alias Precedence​

Aliases are resolved in this order:

  1. Exact alias match - terraform → hashicorp/terraform
  2. Registry search - If no alias, search all registries by priority
  3. Error - Tool not found in aliases or registries

Common Alias Patterns​

HashiCorp Tools​

atmos.yaml
toolchain:
  aliases:
    terraform: hashicorp/terraform
    tf: hashicorp/terraform
    packer: hashicorp/packer
    vault: hashicorp/vault
    consul: hashicorp/consul
    nomad: hashicorp/nomad
    waypoint: hashicorp/waypoint

Kubernetes Ecosystem​

atmos.yaml
toolchain:
  aliases:
    kubectl: kubernetes-sigs/kubectl
    k: kubernetes-sigs/kubectl     # Very short
    helm: helm/helm
    k9s: derailed/k9s
    kustomize: kubernetes-sigs/kustomize
    skaffold: GoogleContainerTools/skaffold

Cloud Provider CLIs​

atmos.yaml
toolchain:
  aliases:
    aws: aws/aws-cli
    awscli: aws/aws-cli
    az: Azure/azure-cli
    azure: Azure/azure-cli
    gcloud: google-cloud-sdk/google-cloud-sdk

Terraform Ecosystem​

atmos.yaml
toolchain:
  aliases:
    terraform: hashicorp/terraform
    opentofu: opentofu/opentofu
    tofu: opentofu/opentofu
    terragrunt: gruntwork-io/terragrunt
    tg: gruntwork-io/terragrunt
    tflint: terraform-linters/tflint
    tfsec: aquasecurity/tfsec
    checkov: bridgecrewio/checkov

Using Aliases in Commands​

Aliases work with all toolchain commands:

# Install
atmos toolchain install terraform@1.9.8
atmos toolchain install tf@1.9.8

# Add to .tool-versions
atmos toolchain add terraform@1.9.8

# Remove from .tool-versions
atmos toolchain remove terraform

# Execute
atmos toolchain exec terraform -- version
atmos toolchain exec tf -- version

# Get information
atmos toolchain info terraform
atmos toolchain which tf

# Search
atmos toolchain search terraform

Using Aliases in .tool-versions​

Aliases work in .tool-versions files:

.tool-versions
terraform 1.9.8
tf 1.9.8              # Same as terraform
kubectl 1.28.0
helm 3.13.0
NOTE:

Both terraform and tf resolve to hashicorp/terraform, so they represent the same tool. Use consistent naming to avoid confusion.

Listing Configured Aliases​

Use atmos toolchain aliases to list effective built-in and configured aliases. Configured aliases take precedence when names overlap.

atmos toolchain aliases
atmos toolchain aliases --format=json
atmos toolchain aliases --format=yaml

The default table is sorted by alias name. JSON and YAML output are alias-to-target mappings. Targets are shown as defined; listing does not resolve alias chains, query registries, or install tools.

Aliases with Custom Registries​

Aliases work with all registry types:

atmos.yaml
toolchain:
  # Aliases
  aliases:
    my-tool: corp/internal-cli
    internal: corp/internal-cli

  # Inline registry
  registries:
    - name: corporate
      type: atmos
      priority: 150
      tools:
        corp/internal-cli:
          type: http
          url: "https://artifacts.corp.com/cli/{{.Version}}/binary"

Usage:

# Both work
atmos toolchain install my-tool@1.0.0
atmos toolchain install corp/internal-cli@1.0.0

Complete Example​

atmos.yaml
toolchain:
  install_path: ".tools"
  file_path: ".tool-versions"

  # Tool name aliases
  aliases:
    # HashiCorp
    terraform: hashicorp/terraform
    tf: hashicorp/terraform
    packer: hashicorp/packer
    vault: hashicorp/vault
    consul: hashicorp/consul

    # OpenTofu
    opentofu: opentofu/opentofu
    tofu: opentofu/opentofu

    # Kubernetes
    kubectl: kubernetes-sigs/kubectl
    k: kubernetes-sigs/kubectl
    helm: helm/helm
    k9s: derailed/k9s

    # Terraform ecosystem
    terragrunt: gruntwork-io/terragrunt
    tg: gruntwork-io/terragrunt
    tflint: terraform-linters/tflint
    tfsec: aquasecurity/tfsec

    # AWS
    aws: aws/aws-cli
    awscli: aws/aws-cli

  # Registries
  registries:
    - name: aqua
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10

Best Practices​

  1. Use consistent naming - Don't mix aliases and full names in .tool-versions
  2. Document custom aliases - Add comments in atmos.yaml for team awareness
  3. Keep aliases simple - Use common abbreviations (tf, k, tg)
  4. Avoid conflicts - Don't create aliases that match existing tool names
  5. Team agreement - Ensure team members use the same aliases

Related Documentation​