Skip to main content

atmos toolchain install

Install CLI tools required by your Atmos components, commands, and workflows. This command downloads and sets up the exact tool versions specified in your toolchain configuration, ensuring consistent execution across your team.

atmos toolchain install --help

Usage​

Execute the toolchain install command like this:

atmos toolchain install

Examples​

# Install a single tool
atmos toolchain install terraform@1.9.8
atmos toolchain install hashicorp/terraform@1.5.0

# Install multiple tools in a single command
atmos toolchain install opentofu@1.6.0 tflint@0.50.0 kubectl@1.29.0
atmos toolchain install terraform helm kubectl tflint

# Limit this batch to two concurrent installs
atmos toolchain install --max-concurrency 2 opentofu@1.6.0 tflint@0.50.0 kubectl@1.29.0

# Install all tools from .tool-versions file
atmos toolchain install

Arguments​

tool@version... (optional)

One or more tools to install from the registry. Each tool can be a short name (alias) or full owner/repo format. If omitted, installs all tools from .tool-versions file.

Examples: terraform@1.9.8, hashicorp/terraform@1.5.0, kubectl@1.28.0

Flags​

--default (optional)

Set installed version as default (front of .tool-versions)

--reinstall (optional)

Reinstall even if already installed

--max-concurrency (optional)

Maximum number of tools to install concurrently. The default is 4. Use a positive integer; values lower than 1 are rejected. This option applies when installing multiple explicit tools or all tools from .tool-versions.

Parallel Install Configuration​

Independent tools in a batch install run concurrently, while Atmos coordinates shared downloads, extraction directories, version files, and lockfiles safely. Set a project default in atmos.yaml, or override it for a single command:

toolchain:
  max_concurrency: 4
ATMOS_TOOLCHAIN_MAX_CONCURRENCY=6 atmos toolchain install
atmos toolchain install --max-concurrency 8

Concurrency is resolved in this order: --max-concurrency, ATMOS_TOOLCHAIN_MAX_CONCURRENCY, toolchain.max_concurrency, then the default of 4.

Frozen Installs​

Enable frozen mode in CI and security-sensitive environments. Prepare, review, and commit the lockfile for the required tools and platforms first. Set toolchain.frozen_lock_file: true in atmos.yaml, or enable it for a CI command:

ATMOS_TOOLCHAIN_FROZEN_LOCK_FILE=true atmos toolchain install

Every requested version must have a URL and checksum for the current platform in the existing lockfile, including tools whose binaries are already cached. Missing entries and checksum mismatches fail. Frozen installation leaves .tool-versions and the artifact lockfile unchanged.

Ordinary installs record missing lock entries after successful extraction and preserve existing matching entries. Automatic installs triggered by commands, dependencies, proxies, or Atmos version switching do not change .tool-versions.

See toolchain lockfile configuration for paths, lock generation, and frozen-mode limitations.

How Tools Are Installed on Disk​

Atmos installs each tool under a version-specific directory (<install_path>/bin/<owner>/<repo>/<version>/) and adapts the on-disk layout to the shape of the downloaded archive:

  • Single-binary tools (for example jq, terraform, kubectl) are placed directly in the version directory as a flat executable.
  • Multi-file ("onedir") tools (for example aws/aws-cli and nodejs/node) ship a binary together with runtime siblings — a bundled language runtime, shared libraries, or node_modules. For these, Atmos preserves the complete extracted archive under a .pkg subdirectory and records each registry entrypoint's real path (such as aws, node, npm, npx) in a small sidecar manifest. This keeps each executable next to the files it needs at runtime, matching how the upstream aqua CLI installs the same packages.

Atmos does not create symlinks to expose these entrypoints — a design choice used consistently across Atmos's install/provisioning code. which resolves directly to the real, nested path (for example .../24.18.0/.pkg/node-v24.18.0-darwin-arm64/bin/node), and atmos toolchain env, exec, and which all resolve it the same way — including every command a multi-command package exposes, whose directories are all added to PATH. Because exposure needs no symlink, this works identically on macOS, Linux, and Windows with no elevated privileges or Developer Mode required.

The only symlinks a onedir install may contain are ones the upstream archive itself ships (for example Node's npm, which the archive links relatively as ../lib/node_modules/... on Unix). Atmos recreates each such link inside the preserved .pkg tree after extraction, through a single validated step, so the tool functions identically to how it would if installed from its original archive; the links are never created by Atmos's exposure logic. Each link is reproduced with the archive's original relative target, so it resolves relative to the link's own directory and works regardless of whether the install path is absolute or relative (such as .tools). The link's resolved target is still validated to stay inside the .pkg tree.

On Windows, where creating a symlink normally requires Developer Mode or elevated privilege, an archive's own file symlink is reproduced as a hard link (or a copy if hard-linking is unavailable), so packages that ship such links still install without elevation. Archives that ship directory symlinks remain unsupported on Windows without the required privilege.

Recovering an Interrupted Install​

An interrupted multi-file install, failed rollback, or failed backup cleanup can leave .atmos-onedir.json.bak in the affected version directory. Atmos preserves that snapshot and any .pkg.bak tree and refuses another install into that directory. Recovery is intentionally manual: the snapshot alone cannot tell whether installation stopped before committing or succeeded but could not remove its backups. Automatically restoring it could replace a successful installation with the previous version's files.

To recover without discarding either installation:

  1. Stop Atmos installs and all processes using this tool, including any shells with its directory in PATH. On Windows, close processes holding its files open before attempting the move.
  2. Before moving anything, confirm that the pinned archive is accessible from its configured source or cache with the original credentials and verification settings. If it is unavailable, leave the installation in place and resolve access first. Locate the version directory containing the snapshot named in the error: <install_path>/bin/<owner>/<repo>/<version>/. Move that entire directory, including hidden files, to a unique backup location outside the toolchain install directory. Keep .pkg, .pkg.bak, both manifest files, and any flat executable together. Do not delete just the snapshot or copy its JSON over the active manifest; it contains encoded recovery metadata, not a manifest.
  3. From the original project and configuration, reinstall the same exact tool version, for example atmos toolchain install nodejs/node@24.18.0 --reinstall. Use the original registry and verification settings. If frozen mode is enabled, keep it enabled and retain the original lockfile. Reinstallation still depends on the archive remaining available. If it fails, stop all tool and install processes again, move any newly created version directory to a separate backup, and return the original saved directory to its exact former path. Do not merge or overwrite the directories. This restores a previously usable committed install; an already interrupted install still needs repair.
  4. Check atmos toolchain which <owner>/<repo>@<version> and exercise the tool before removing the backup. Restart shells that held the old tool path.

If the only message was "Tool installed, but onedir recovery cleanup needs attention", the new installation has committed and remains usable. Do not restore the old tree or manifest over it. Use the same backup-and-reinstall procedure when you can stop the tool to clear the leftover recovery state.

Try it out​

Copy the example into a new directory and make it your own:

atmos init examples/toolchain
cd toolchain

Install the pinned jq binary into this project. Requires network access.

atmos toolchain install jq
Explore the example →Initialization and repository settings