# 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:

**File:** `atmos.yaml`

```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:

**File:** `atmos.yaml`

```yaml
version:
  check:
    enabled: false
```

Or via environment variable:

```bash
export ATMOS_VERSION_CHECK_ENABLED=false
```

### Check Weekly

For less frequent checks, such as weekly:

**File:** `atmos.yaml`

```yaml
version:
  check:
    enabled: true
    frequency: weekly
```

### Custom Frequency

Set a custom check interval of 12 hours:

**File:** `atmos.yaml`

```yaml
version:
  check:
    enabled: true
    frequency: 12h
```

Or using seconds:

**File:** `atmos.yaml`

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

## Force Version Check

To check for updates immediately, regardless of configuration:

```bash
atmos version --check
```

This bypasses the frequency setting and checks the [Atmos releases](https://github.com/cloudposse/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](/install) 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

- [`atmos version`](/cli/commands/version/usage) — Display Atmos version and check for updates