atmos-toolchain（atmos 工具链）

Atmos Toolchain

Purpose

The Atmos toolchain manages CLI tool installation and versioning natively, using the Aqua package registry ecosystem. It replaces external version managers (asdf, mise, aqua CLI) with a built-in system that integrates directly with atmos.yaml configuration.

Core Concepts

.tool-versions File

The .tool-versions file (asdf-compatible format) declares which tools and versions a project needs:

terraform 1.9.8
opentofu 1.10.3
kubectl 1.28.0
helm 3.13.0
jq 1.7.1

• One tool per line, format: toolname version [version2 version3...]
• Multiple versions per tool are supported; first version is the default
• File location: project root (default), overridable via toolchain.file_path in atmos.yaml

Tool Installation Path

Tools are installed to .tools/ (default) in a structured layout:

.tools/bin/{os}/{tool}/{version}/{binary}

Override via toolchain.install_path in atmos.yaml or ATMOS_TOOLCHAIN_PATH env var.

Registries

Atmos supports three registry types for discovering and downloading tools:

Aqua Registry -- The primary source, providing 1,000+ tools:

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

Inline (Atmos) Registry -- Define tools directly in atmos.yaml:

registries:
  - name: custom
    type: atmos
    priority: 150
    tools:
      owner/repo:
        type: github_release
        url: "asset_{{.Version}}_{{.OS}}_{{.Arch}}"
        format: tar.gz

File-Based Registry -- Local or remote Aqua-format files:

registries:
  - name: corporate
    type: aqua
    source: file://./custom-registry.yaml
    priority: 100

Priority System: Higher numbers are checked first. First match wins. Typical ordering: inline (150) > corporate (100) > public aqua (10).

Aliases

Map short names to fully qualified tool identifiers:

toolchain:
  aliases:
    terraform: hashicorp/terraform
    tf: hashicorp/terraform
    kubectl: kubernetes-sigs/kubectl

Configuration in atmos.yaml

toolchain:
  install_path: .tools              # Where to install tools
  file_path: .tool-versions         # Path to version file

  aliases:
    terraform: hashicorp/terraform
    tf: hashicorp/terraform

  registries:
    # Inline tools (highest priority)
    - name: my-tools
      type: atmos
      priority: 150
      tools:
        jqlang/jq:
          type: github_release
          url: "jq-{{.OS}}-{{.Arch}}"

    # Aqua registry (fallback)
    - name: aqua
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10

Key Commands

Installation

atmos toolchain install                    # Install all tools from .tool-versions
atmos toolchain install terraform@1.9.8    # Install specific tool and version
atmos toolchain uninstall terraform@1.9.8  # Remove installed tool
atmos toolchain clean                      # Remove all installed tools and cache

Version Management

atmos toolchain add terraform              # Add tool to .tool-versions (latest)
atmos toolchain add terraform@1.9.8        # Add with specific version
atmos toolchain remove terraform           # Remove from .tool-versions
atmos toolchain set terraform 1.9.8        # Set default version
atmos toolchain get terraform              # Get version from .tool-versions

Discovery

atmos toolchain search terraform           # Search across registries
atmos toolchain info hashicorp/terraform   # Display tool configuration
atmos toolchain list                       # Show installed tools
atmos toolchain which terraform            # Show full path to binary
atmos toolchain du                         # Show disk usage

Execution

atmos toolchain exec terraform@1.9.8 -- plan    # Run specific version
atmos toolchain env --format=bash                # Export PATH for shell
atmos toolchain path                             # Print PATH entries

Registry Management

atmos toolchain registry list              # List all registries
atmos toolchain registry list aqua         # List tools in specific registry
atmos toolchain registry search jq         # Search across registries

Environment Variables

Precedence Order

1. CLI flags (highest)
2. Environment variables
3. atmos.yaml configuration
4. Defaults (lowest)

Shell Integration

Add to ~/.bashrc or ~/.zshrc for automatic PATH setup:

eval "$(atmos toolchain env --format=bash)"

Other shell formats: --format=fish, --format=powershell, --format=github (for CI).

Template Variables in Registries

Aqua and inline registries support Go templates in asset URLs:

Common Patterns

Project Setup

# atmos.yaml
toolchain:
  aliases:
    terraform: hashicorp/terraform
    kubectl: kubernetes-sigs/kubectl
  registries:
    - name: aqua
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10

# .tool-versions
hashicorp/terraform 1.9.8
kubernetes-sigs/kubectl 1.28.0
helmfile/helmfile 0.168.0

# Install everything
atmos toolchain install

# Verify
atmos toolchain list

CI/CD Integration

# GitHub Actions
- name: Install tools
  run: |
    atmos toolchain install
    eval "$(atmos toolchain env --format=github)"

Custom Tool Registry

toolchain:
  registries:
    - name: internal
      type: atmos
      priority: 150
      tools:
        company/internal-tool:
          type: github_release
          url: "internal-tool_{{.Version}}_{{.OS}}_{{.Arch}}.tar.gz"
          format: tar.gz
    - name: aqua
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10

Unsupported Aqua Features

These Aqua features are intentionally not supported to keep Atmos focused:

• github_content, github_archive, go_build, cargo package types
• version_filter, version_expr version manipulation
• import (use multiple registries instead)
• command_aliases (use toolchain.aliases in atmos.yaml)
• cosign, minisign, slsa_provenance signature verification