fix(version): honor ATMOS_USE_VERSION env var for version re-exec

[Erik Osterman (Cloud Posse) (osterman)]

what

• Honor the documented ATMOS_USE_VERSION environment variable so Atmos actually switches to (and downloads, if needed) the requested version during early re-exec.
• resolveRequestedVersion now reads ATMOS_USE_VERSION, with precedence ATMOS_VERSION_USE > ATMOS_USE_VERSION > ATMOS_VERSION > version.use.
• cmd/root.go also honors ATMOS_USE_VERSION from the environment so version-management commands (e.g. atmos version) re-exec on it just like the --use-version flag.
• Add a table case and a precedence test covering the new behavior.

why

• ATMOS_USE_VERSION is advertised as the primary env var (docs at website/docs/cli/environment-variables.mdx and the flag binding WithEnvVars("use-version", "ATMOS_USE_VERSION")), but the re-exec resolver never read it — it only checked the internal ATMOS_VERSION_USE (set solely by the CLI flag), the ATMOS_VERSION alias, and version.use config.
• An env-populated flag is not marked Changed() and maps to viper key use-version rather than version.use, so ATMOS_USE_VERSION fell through every code path — setting it was a complete no-op.
• This surfaced in CI where ATMOS_USE_VERSION was set for atmos describe affected --upload but Atmos ran the already-installed version instead of switching. This brings the code in line with the existing documentation.

references

• Docs already describe the intended behavior: website/docs/cli/environment-variables.mdx

Summary by CodeRabbit

• New Features

  • Added support for the ATMOS_USE_VERSION environment variable as an alternative to the --use-version CLI flag for version selection.
  • Updated version resolution precedence to check environment variables in defined order.

• Tests

  • Extended test coverage for environment variable version selection scenarios.

[atmos-pro]

Tip

Atmos Pro  

No affected stacks workflow was detected for this pull request.
If this is expected, no action is needed.
Learn More. Ask AI.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues found.

Scanned Files

None

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7a8add58-91a8-433a-b5fc-45bc66c9058f

📥 Commits

Reviewing files that changed from the base of the PR and between edca67f and 28d7429.

📒 Files selected for processing (3)

• cmd/root.go
• pkg/version/reexec.go
• pkg/version/reexec_test.go

---

📝 Walkthrough

Walkthrough

The PR introduces ATMOS_USE_VERSION as a public environment variable that mirrors --use-version flag functionality. It defines the env var constant, updates version resolution precedence to check it alongside existing env vars, hooks it into the CLI root command, and validates the behavior and precedence ordering with tests.

Changes

ATMOS_USE_VERSION Environment Variable Support

Layer / File(s)	Summary
Version resolution precedence with new env var pkg/version/reexec.go	Adds UseVersionEnvVar constant for ATMOS_USE_VERSION and updates resolveRequestedVersion to check this env var in precedence order: ATMOS_VERSION_USE, then ATMOS_USE_VERSION, then ATMOS_VERSION, before config fallback.
CLI root command integration cmd/root.go	Updates PersistentPreRun to check ATMOS_USE_VERSION env var when --use-version flag is not provided, setting explicitVersion and explicitVersionRequested to trigger downstream re-exec behavior.
Environment variable and precedence tests pkg/version/reexec_test.go	Extends EnvVarVersions test with ATMOS_USE_VERSION case and adds UseEnvVarPrecedence test validating correct resolution order when multiple version env vars are present.

Possibly related PRs

• cloudposse/atmos#2223: Updates documentation for version.use and --use-version environment variable precedence.

Suggested labels

patch

Suggested reviewers

• aknysh
• mcalhoun

---

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(version): honor ATMOS_USE_VERSION env var for version re-exec' directly and clearly describes the main change: making Atmos respect the ATMOS_USE_VERSION environment variable during version re-execution.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch osterman/vancouver-v11

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.77%. Comparing base (8dc0bc0) to head (28d7429).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
cmd/root.go	25.00%	2 Missing and 1 partial ⚠️

❌ Your patch check has failed because the patch coverage (50.00%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2556      +/-   ##
==========================================
+ Coverage   78.70%   78.77%   +0.06%     
==========================================
  Files        1192     1194       +2     
  Lines      113940   114110     +170     
==========================================
+ Hits        89682    89888     +206     
+ Misses      19328    19281      -47     
- Partials     4930     4941      +11     

Flag	Coverage Δ
unittests	78.77% <50.00%> (+0.06%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
pkg/version/reexec.go	93.51% <100.00%> (+0.07%)	⬆️
cmd/root.go	67.81% <25.00%> (-0.21%)	⬇️

... and 10 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.