atmos-toolchain

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Atmos Toolchain

Atmos 工具链

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.

Atmos工具链原生支持CLI工具的安装与版本管理，基于Aqua包注册表生态系统构建。它通过一个直接集成atmos.yaml配置的内置系统，替代了asdf、mise、aqua CLI等外部版本管理器。

Core Concepts

核心概念

.tool-versions File

.tool-versions 文件

The

.tool-versions

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

text

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-versions

文件（与asdf兼容格式）用于声明项目所需的工具及版本：

text

terraform 1.9.8
opentofu 1.10.3
kubectl 1.28.0
helm 3.13.0
jq 1.7.1

每行一个工具，格式：

工具名 版本号 [版本号2 版本号3...]

支持单个工具对应多个版本；第一个版本为默认版本
文件位置：默认在项目根目录，可通过atmos.yaml中的
```
toolchain.file_path
```
覆盖

Tool Installation Path

工具安装路径

Tools are installed to

.tools/

(default) in a structured layout:

text

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

Override via

toolchain.install_path

in atmos.yaml or

ATMOS_TOOLCHAIN_PATH

env var.

工具默认安装到

.tools/

目录，采用结构化布局：

text

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

可通过atmos.yaml中的

toolchain.install_path

或环境变量

ATMOS_TOOLCHAIN_PATH

覆盖默认路径。

Registries

注册表

Atmos supports three registry types for discovering and downloading tools:

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

yaml

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:

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:

yaml

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).

Atmos支持三种注册表类型，用于发现和下载工具：

Aqua 注册表 -- 主要源，提供1000+工具：

yaml

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

内联（Atmos）注册表 -- 直接在atmos.yaml中定义工具：

yaml

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

基于文件的注册表 -- 本地或远程的Aqua格式文件：

yaml

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

优先级系统：数值越高，优先级越高。匹配到第一个符合条件的工具即停止查找。典型优先级顺序：内联（150）> 企业内部（100）> 公共Aqua（10）。

Aliases

别名

Map short names to fully qualified tool identifiers:

yaml

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

将短名称映射到完整的工具标识符：

yaml

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

Configuration in atmos.yaml

atmos.yaml 配置

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

yaml

toolchain:
  install_path: .tools              # 工具安装目录
  file_path: .tool-versions         # 版本文件路径

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

  registries:
    # 内联工具（最高优先级）
    - name: my-tools
      type: atmos
      priority: 150
      tools:
        jqlang/jq:
          type: github_release
          url: "jq-{{.OS}}-{{.Arch}}"

    # Aqua注册表（ fallback）
    - name: aqua
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10

Key Commands

关键命令

Installation

安装

bash

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

bash

atmos toolchain install                    # 安装.tool-versions中的所有工具
atmos toolchain install terraform@1.9.8    # 安装指定工具及版本
atmos toolchain uninstall terraform@1.9.8  # 卸载已安装的工具
atmos toolchain clean                      # 移除所有已安装工具及缓存

Version Management

版本管理

bash

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

bash

atmos toolchain add terraform              # 将最新版本的工具添加到.tool-versions
atmos toolchain add terraform@1.9.8        # 添加指定版本的工具
atmos toolchain remove terraform           # 从.tool-versions中移除工具
atmos toolchain set terraform 1.9.8        # 设置默认版本
atmos toolchain get terraform              # 获取.tool-versions中的工具版本

Discovery

发现

bash

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

bash

atmos toolchain search terraform           # 在所有注册表中搜索工具
atmos toolchain info hashicorp/terraform   # 显示工具配置信息
atmos toolchain list                       # 查看已安装的工具
atmos toolchain which terraform            # 显示工具二进制文件的完整路径
atmos toolchain du                         # 显示磁盘占用情况

Execution

执行

bash

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

bash

atmos toolchain exec terraform@1.9.8 -- plan    # 运行指定版本的工具
atmos toolchain env --format=bash                # 导出PATH到shell环境
atmos toolchain path                             # 打印PATH条目

Registry Management

注册表管理

bash

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

bash

atmos toolchain registry list              # 列出所有注册表
atmos toolchain registry list aqua         # 列出指定注册表中的工具
atmos toolchain registry search jq         # 在所有注册表中搜索工具

Environment Variables

环境变量

Variable	Description
`ATMOS_GITHUB_TOKEN` / `GITHUB_TOKEN`	GitHub token for higher API rate limits
`ATMOS_TOOL_VERSIONS`	Override .tool-versions file path
`ATMOS_TOOLCHAIN_PATH`	Override tool installation directory
`ATMOS_TOOLCHAIN_ENV_FORMAT`	Default format for `env` command

变量	描述
`ATMOS_GITHUB_TOKEN` / `GITHUB_TOKEN`	GitHub令牌，用于提升API调用速率限制
`ATMOS_TOOL_VERSIONS`	覆盖.tool-versions文件的路径
`ATMOS_TOOLCHAIN_PATH`	覆盖工具安装目录
`ATMOS_TOOLCHAIN_ENV_FORMAT`	`env` 命令的默认输出格式

Precedence Order

优先级顺序

CLI flags (highest)
Environment variables
atmos.yaml configuration
Defaults (lowest)

CLI参数（最高优先级）
环境变量
atmos.yaml配置
默认值（最低优先级）

Shell Integration

Shell 集成

Add to

~/.bashrc

~/.zshrc

for automatic PATH setup:

bash

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

Other shell formats:

--format=fish

--format=powershell

--format=github

(for CI).

将以下内容添加到

~/.bashrc

或

~/.zshrc

中，实现自动配置PATH：

bash

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

支持的其他shell格式：

--format=fish

、

--format=powershell

、

--format=github

（适用于CI环境）。

Template Variables in Registries

注册表中的模板变量

Aqua and inline registries support Go templates in asset URLs:

Variable	Description
`{{.Version}}`	Full version string
`{{trimV .Version}}`	Version without 'v' prefix
`{{.OS}}`	Operating system (linux, darwin, windows)
`{{.Arch}}`	Architecture (amd64, arm64)

Aqua和内联注册表支持在资源URL中使用Go模板：

变量	描述
`{{.Version}}`	完整版本字符串
`{{trimV .Version}}`	去除'v'前缀的版本号
`{{.OS}}`	操作系统（linux、darwin、windows）
`{{.Arch}}`	架构（amd64、arm64）

Common Patterns

常见使用模式

Project Setup

项目初始化

yaml

undefined

yaml

undefined

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


```text

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


```text

.tool-versions

hashicorp/terraform 1.9.8 kubernetes-sigs/kubectl 1.28.0 helmfile/helmfile 0.168.0


```bash

hashicorp/terraform 1.9.8 kubernetes-sigs/kubectl 1.28.0 helmfile/helmfile 0.168.0


```bash

Install everything

安装所有工具

atmos toolchain install

Verify

验证安装

atmos toolchain list

undefined

atmos toolchain list

undefined

CI/CD Integration

CI/CD 集成

yaml

undefined

yaml

undefined

GitHub Actions

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

undefined

name: 安装工具 run: | atmos toolchain install eval "$(atmos toolchain env --format=github)"

undefined

Custom Tool Registry

自定义工具注册表

yaml

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

yaml

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

不支持的Aqua功能

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

为保持Atmos的专注性，以下Aqua功能未被支持：

github_content

、

github_archive

、

go_build

、

cargo

包类型

```
version_filter
```
、
```
version_expr
```
版本操作
```
import
```
（建议使用多个注册表替代）
```
command_aliases
```
（使用atmos.yaml中的
```
toolchain.aliases
```
替代）
```
cosign
```
、
```
minisign
```
、
```
slsa_provenance
```
签名验证