Skip to main content

Version Check

Configure automatic version checking and update notifications for Atmos CLI. Control how frequently Atmos checks for new releases and whether update notifications are displayed.

Configuration​

Version checking is configured in the version section:

atmos.yaml
version:
  check:
    enabled: true
    frequency: daily

Configuration Options​

version.check.enabled

Enable or disable automatic version checking. When disabled, Atmos will not check for updates unless explicitly requested with atmos version --check.

Default: true

Can also be set via ATMOS_VERSION_CHECK_ENABLED environment variable.

version.check.frequency

How often Atmos checks for new versions. Supports three formats:

Predefined Keywords:

  • minute — Check every minute
  • hourly — Check every hour
  • daily — Check once per day (default)
  • weekly — Check once per week
  • monthly — Check once per month
  • yearly — Check once per year

Duration with Suffix:

  • 1m — 1 minute
  • 5h — 5 hours
  • 2d — 2 days

Integer (seconds):

  • 3600 — Check every 3600 seconds (1 hour)

Default: daily

If an invalid value is provided, defaults to daily.

Examples​

Disable Version Checks​

To disable automatic version checking entirely:

atmos.yaml
version:
  check:
    enabled: false

Or via environment variable:

export ATMOS_VERSION_CHECK_ENABLED=false

Check Weekly​

For less frequent checks, such as weekly:

atmos.yaml
version:
  check:
    enabled: true
    frequency: weekly

Custom Frequency​

Set a custom check interval of 12 hours:

atmos.yaml
version:
  check:
    enabled: true
    frequency: 12h

Or using seconds:

atmos.yaml
version:
  check:
    enabled: true
    frequency: 43200  # 12 hours in seconds

Force Version Check​

To check for updates immediately, regardless of configuration:

atmos version --check

This bypasses the frequency setting and checks the Atmos releases page on GitHub for the latest version.

Upgrade Notifications​

When a newer release is available, Atmos suggests an upgrade method based on the running executable's installation location and local package ownership. For example, an Atmos binary installed through Homebrew receives brew upgrade atmos. Having Homebrew installed does not change the suggestion for an Atmos binary managed by mise or another installer.

Detection supports Homebrew, DEB, RPM, APK, Scoop, mise, asdf, aqua, Nix, Go installations, and Atmos's native version manager. It respects custom installation roots and resolves executable symlinks. Native installations selected through version.use receive native version-manager guidance.

For DEB, RPM, and APK installations, package ownership does not establish whether the package came from a repository. The notification presents repository upgrade commands conditionally and also links to the releases page for downloading and installing a newer package directly.

For version managers, the notification includes any required configuration step: installing a newer binary may not change the version selected by .tool-versions, mise or aqua configuration, or an Atmos version pin. Nix installations receive guidance to update their controlling configuration or input.

For Go installations, the suggested command sets GOBIN to the directory containing the running executable, so it updates that installation even when GOPATH contains multiple entries. Windows Go hints explicitly use PowerShell syntax.

If Atmos cannot identify its installation, it links to the installation instructions without suggesting a command. If a recognized manager is unavailable on PATH, it provides written guidance instead. Detection uses local, read-only checks with a one-second command deadline; it does not refresh package indexes or install anything.

These hints appear in automatic notifications and atmos version --check. The configured check frequency is unchanged; there is no additional delay based on a release's age. A release announced on GitHub may not yet be available through a third-party package repository.

Environment Variables​

ATMOS_VERSION_CHECK_ENABLED
Override the version.check.enabled setting. Set to false to disable version checking.

Related Commands​