Skip to main content

atmos toolchain update

Update one or more tools to their newest available version, without leaving your .tool-versions file in a broken or ambiguous state. This is the command to reach for when you know a tool should move forward — add/install intentionally never bump an already-configured version on their own.

atmos toolchain update --help

Usage​

Execute the toolchain update command like this:

atmos toolchain update

How Updates Are Resolved​

update looks at each tool's current pin in .tool-versions and decides what, if anything, to do:

  • Pinned to latest — re-resolved to the newest version and reinstalled.
  • Pinned to an exact version (for example 1.9.8 or a tool-specific tag like jq-1.7.1) — replaced with the newest available version from the registry and reinstalled, if a newer one exists. Already-current tools are reported as up to date and left untouched.
  • Pinned to pr:NNNN, sha:xxxxxxx, or ref:<name> — skipped. update never overrides an explicit source selection like this — even ref:<name>, which can move over time, is left alone so it keeps tracking the name you chose rather than being silently replaced with a resolved version. Use atmos toolchain add to change one explicitly.

update always replaces the tool's default version rather than appending — unlike plain add, it never leaves a tool pinned to two versions at once.

For range/constraint-based pinning (^1.2.0, ~>1.0.0, >=1.0.0) instead of exact-version tracking, see dependencies.tools in a stack manifest, or atmos version track — .tool-versions is intentionally exact-version-only.

Examples​

# Update every tool in .tool-versions
atmos toolchain update

# Update specific tools
atmos toolchain update terraform
atmos toolchain update terraform kubectl

# Preview what would change without installing anything
atmos toolchain update --dry-run

# Limit this batch to two concurrent updates
atmos toolchain update --max-concurrency 2

Arguments​

tool... (optional)

One or more tools to update. Each tool can be a short name (alias) or full owner/repo format. If omitted, updates every tool configured in .tool-versions.

Examples: terraform, hashicorp/terraform, kubectl

Flags​

--dry-run (optional)

Report what would change without installing anything or modifying .tool-versions.

--max-concurrency (optional)

Maximum number of tools to update concurrently. The default is 4. Use a positive integer; values lower than 1 are rejected. Resolved the same way as install's --max-concurrency: --max-concurrency, ATMOS_TOOLCHAIN_MAX_CONCURRENCY, toolchain.max_concurrency, then 4.

Related Commands​