# Toolchain Registries

Toolchain registries define where Atmos finds tool metadata and binaries. Atmos supports multiple registry types with priority-based precedence, allowing you to use official registries, corporate mirrors, and custom tool definitions.

> **Key points**
>
> - Multiple registry support with priority ordering
> - Aqua registry integration (1,000+ pre-configured tools)
> - Inline registry for quick prototyping
> - Custom registries for private or corporate tools
> - File-based and URL-based registry sources

## Registry Types

Atmos supports three registry types:

### 1. Aqua Registry

The [Aqua registry](https://github.com/aquaproj/aqua-registry) is a community-maintained collection of 1,000+ CLI tool definitions with battle-tested metadata.

**File:** `atmos.yaml`

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

**Features:**

- Pre-configured tools: terraform, kubectl, helm, aws-cli, and more
- Regular updates from active contributors
- Rich metadata: download URLs, checksums, version mapping
- Proven YAML format used by thousands of teams

### 2. Atmos Inline Registry

Define tools directly in your `atmos.yaml` for quick prototyping or custom tools:

**File:** `atmos.yaml`

```yaml
toolchain:
  registries:
    - name: my-tools
      type: atmos
      priority: 150
      tools:
        stedolan/jq:
          type: github_release
          url: "jq-{{.OS}}-{{.Arch}}"
        mikefarah/yq:
          type: github_release
          url: "yq_{{.Version}}_{{.OS}}_{{.Arch}}.tar.gz"
```

**Features:**

- No external files needed
- Perfect for quick prototyping or small tool sets
- Supports all template variables: `{{.OS}}`, `{{.Arch}}`, `{{.Version}}`, `{{trimV .Version}}`
- Tools defined using `owner/repo` format

### 3. Custom File-Based Registry

Use custom registry files for corporate or private tools:

**File:** `atmos.yaml`

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

## Registry Source Patterns

Atmos supports two registry file organization patterns:

### Single Index File (Recommended)

All tool definitions in one file:

**File:** `atmos.yaml`

```yaml
toolchain:
  registries:
    - name: custom
      type: aqua
      source: file://./registry.yaml  # Ends with .yaml or .yml
      priority: 100
```

**File:** `registry.yaml`

```yaml
packages:
  - type: github_release
    repo_owner: hashicorp
    repo_name: terraform
    asset: "terraform_{{.Version}}_{{.OS}}_{{.Arch}}.zip"

  - type: github_release
    repo_owner: opentofu
    repo_name: opentofu
    asset: "tofu_{{.Version}}_{{.OS}}_{{.Arch}}.zip"
```

**Benefits:**

- Simplest to maintain
- All tools in one place
- Matches official Aqua registry structure

### Per-Package Directory

Separate file per package for larger registries:

**File:** `atmos.yaml`

```yaml
toolchain:
  registries:
    - name: custom
      type: aqua
      source: file://./pkgs/  # Directory, not .yaml file
      priority: 100
```

**Directory structure:**

```
pkgs/
├── hashicorp/
│   └── terraform/
│       └── registry.yaml
└── opentofu/
    └── opentofu/
        └── registry.yaml
```

Each `registry.yaml` contains ONE package definition.

**Benefits:**

- Better organization for large registries
- Per-tool versioning
- Easier to maintain individual tools

## Priority System

Registries are checked in priority order (highest to lowest):

**File:** `atmos.yaml`

```yaml
toolchain:
  registries:
    # Checked first (highest priority)
    - name: corporate
      type: atmos
      priority: 150
      tools:
        internal/custom-tool:
          type: http
          url: "https://artifacts.corp.com/custom-tool/{{.Version}}/binary"

    # Checked second
    - name: corporate-mirror
      type: aqua
      source: file://./corporate-registry/registry.yaml
      priority: 100

    # Checked third
    - name: internal-mirror
      type: aqua
      source: https://github-mirror.corp.com/aqua-registry/pkgs
      priority: 50

    # Checked last (lowest priority)
    - name: aqua-public
      type: aqua
      source: https://github.com/aquaproj/aqua-registry/tree/main/pkgs
      priority: 10
```

**Resolution order:**

1. Corporate inline tools (priority: 150)
2. Corporate registry file (priority: 100)
3. Internal mirror (priority: 50)
4. Public Aqua registry (priority: 10)
5. Error if tool not found in any registry

## Registry Configuration Options

- **`name`**
  Unique identifier for the registry
- **`type`**

  Registry type:
  - `aqua` - Aqua registry format (file or URL)
  - `atmos` - Inline tool definitions
- **`source`**

  Registry location (required for `aqua` type):
  - File: `file://./path/to/registry.yaml`
  - Directory: `file://./path/to/pkgs/`
  - URL: `https://github.com/aquaproj/aqua-registry/tree/main/pkgs`
- **`priority`**

  Search priority (higher numbers checked first):
  - Inline registries: 100-200
  - Corporate registries: 50-100
  - Public registries: 1-50
  - Default: 10
- **`tools`**

  Inline tool definitions (required for `atmos` type):
  - Key format: `owner/repo`
  - Value: Tool configuration object

## Tool Definition Format

Tools in Aqua registries use this format:

**File:** `registry.yaml`

```yaml
packages:
  - type: github_release
    repo_owner: hashicorp
    repo_name: terraform
    asset: "terraform_{{.Version}}_{{.OS}}_{{.Arch}}.zip"
    format: zip
    version_constraint: "semver"
    version_overrides:
      - version_constraint: ">= 1.0.0"
        asset: "terraform_{{.Version}}_{{.OS}}_{{.Arch}}.zip"
```

### Template Variables

Use template variables in asset URLs:

- **`{{.Version}}`**
  Full version string (e.g., 
  `1.9.8`
  )
- **`{{trimV .Version}}`**
  Version without 'v' prefix (e.g., 
  `1.9.8`
   from 
  `v1.9.8`
  )
- **`{{.OS}}`**
  Operating system (
  `linux`
  , 
  `darwin`
  , 
  `windows`
  )
- **`{{.Arch}}`**
  Architecture (
  `amd64`
  , 
  `arm64`
  )
- **`{{trimPrefix .Version "v"}}`**
  Remove prefix from string
- **`{{trimSuffix .Version "-beta"}}`**
  Remove suffix from string
- **`{{replace .Version "." "_"}}`**
  String replacement

## Package Types

### GitHub Release

Download from GitHub release assets:

**File:** `registry.yaml`

```yaml
packages:
  - type: github_release
    repo_owner: hashicorp
    repo_name: terraform
    asset: "terraform_{{.Version}}_{{.OS}}_{{.Arch}}.zip"
```

### HTTP Download

Download from direct URLs:

**File:** `registry.yaml`

```yaml
packages:
  - type: http
    url: "https://releases.hashicorp.com/terraform/{{trimV .Version}}/terraform_{{trimV .Version}}_{{.OS}}_{{.Arch}}.zip"
```

## Supported Archive Formats

Atmos automatically detects and extracts:

- `.tar.gz` - Gzip-compressed tarballs
- `.zip` - ZIP archives
- `.gz` - Single gzip-compressed binaries
- Raw binaries (no extension)

## Complete Example

**File:** `atmos.yaml`

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

  registries:
    # Corporate inline tools (highest priority)
    - name: corporate
      type: atmos
      priority: 150
      tools:
        corp/internal-cli:
          type: http
          url: "https://artifacts.corp.com/cli/{{.Version}}/cli-{{.OS}}-{{.Arch}}"

    # Corporate Aqua registry mirror
    - name: corporate-aqua
      type: aqua
      source: file://./corporate-registry/registry.yaml
      priority: 100

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

> **Note**
>
> Registry definitions are cached locally for performance. Use `atmos toolchain clean` to clear the cache and force a refresh.

## Related Documentation

- [Toolchain Overview](/cli/configuration/toolchain/) - Basic toolchain configuration
- [Tool Aliases](/cli/configuration/toolchain/aliases) - Define convenient tool name aliases
- [Toolchain Commands](/cli/commands/toolchain/usage) - Full command reference
- [Aqua Registry](https://github.com/aquaproj/aqua-registry) - Browse available tools