Skip to main content

Toolchain Configuration

The toolchain feature enables you to manage CLI tool versions (Terraform, kubectl, helm, etc.) directly within Atmos, ensuring consistency across your team and CI/CD environments.

You will learn

  • Manage tool versions with .tool-versions files
  • Install CLI binaries from GitHub releases and other sources
  • Integrate with the Aqua registry ecosystem for 1,000+ pre-configured tools
  • Version control your tools for team consistency
  • Automatic tool provisioning in workflows

Basic Configuration​

Configure toolchain behavior in your atmos.yaml:

atmos.yaml

# Toolchain configuration
toolchain:
  # Path to .tool-versions file (relative or absolute)
  file_path: ".tool-versions"

  # Directory where tools are installed (relative or absolute)
  install_path: ".tools"

Configuration Options​

file_path

Path to the .tool-versions file that tracks tool versions for your project.

  • Default: .tool-versions
  • Supports relative or absolute paths
  • Compatible with asdf format
install_path

Directory where toolchain binaries will be installed.

  • Default: .tools
  • Supports relative or absolute paths
  • Tools are organized by name and version: .tools/bin/{os}/{tool}/{version}/{tool}
versions_file

Alternative name for file_path. Use file_path for consistency.

tools_dir

Alternative name for install_path. Use install_path for consistency.

Tool Versions File​

Create a .tool-versions file to track tool dependencies:

.tool-versions

terraform 1.9.8
opentofu 1.10.3
kubectl 1.28.0
helm 3.13.0
tflint 0.44.1

This file follows the asdf format:

  • One tool per line
  • Format: <tool-name> <version>
  • Commit to version control for team consistency

Installing Tools​

Install all tools from .tool-versions:

atmos toolchain install

Install a specific tool:

atmos toolchain install terraform@1.9.8
atmos toolchain install kubectl@1.28.0

Directory Structure​

After installation, tools are organized as follows:

.tools/
├── bin/
│   └── darwin/                    # OS-specific directory
│       ├── terraform/
│       │   └── 1.9.8/
│       │       └── terraform      # Binary
│       ├── kubectl/
│       │   └── 1.28.0/
│       │       └── kubectl
│       └── helm/
│           └── 3.13.0/
│               └── helm
└── cache/
    └── downloads/                 # Downloaded archives

Advanced Configuration​

For advanced toolchain features, see:

  • Registries - Configure tool registries (Aqua, custom, inline)
  • Aliases - Define tool name aliases

Complete Example​

atmos.yaml

toolchain:
  # Basic settings
  file_path: ".tool-versions"
  install_path: ".tools"

  # Tool name aliases
  aliases:
    terraform: hashicorp/terraform
    tf: hashicorp/terraform
    tofu: opentofu/opentofu
    kubectl: kubernetes-sigs/kubectl
    helm: helm/helm

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

Environment Variables​

Configure toolchain behavior via environment variables:

ATMOS_TOOLCHAIN_FILE_PATH
Override the tool versions file path
ATMOS_TOOLCHAIN_INSTALL_PATH
Override the tool installation directory
ATMOS_GITHUB_TOKEN or GITHUB_TOKEN

GitHub personal access token for:

  • Higher API rate limits (5,000 req/hour vs 60 unauthenticated)
  • Access to private repositories
  • Better reliability during bulk operations

CLI Precedence​

Configuration is resolved in this order (highest to lowest priority):

  1. CLI flags: atmos toolchain install --install-path=/custom/path
  2. Environment variables: ATMOS_TOOLCHAIN_INSTALL_PATH=/custom/path
  3. Configuration file: toolchain.install_path in atmos.yaml
  4. Defaults: .tools for install_path, .tool-versions for file_path