atmosenv is an Atmos version manager inspired by tfenv.
Just like tfenv manages Terraform versions, atmosenv manages Atmos versions - allowing you to easily switch between different versions on a per-project basis using .atmos-version files.
- Install and manage multiple Atmos versions
- Automatic version switching based on
.atmos-versionfiles - Per-project version pinning
- Homebrew installation support
- Cross-platform (macOS, Linux)
- Shell completion for bash, zsh, and fish
brew tap jamengual/atmosenv
brew install atmosenvgit clone https://github.com/jamengual/atmosenv.git ~/.atmosenvThen add atmosenv to your PATH. Add the following to your shell configuration:
Bash (~/.bashrc or ~/.bash_profile):
export PATH="$HOME/.atmosenv/bin:$PATH"
eval "$(atmosenv init -)"Zsh (~/.zshrc):
export PATH="$HOME/.atmosenv/bin:$PATH"
eval "$(atmosenv init -)"Fish (~/.config/fish/config.fish):
set -gx PATH $HOME/.atmosenv/bin $PATH
atmosenv init - | sourceImportant: atmosenv must be at the beginning of your PATH to take precedence over any other
atmosbinary you may have installed (e.g., via Homebrew). This is the same pattern used by tfenv, rbenv, and other version managers.
# Install the latest Atmos version
atmosenv install latest
# Switch to the installed version
atmosenv use latest
# Verify installation
atmos version
# List installed versions
atmosenv list
# List available versions
atmosenv list-remote# Install a specific version
atmosenv install 1.201.0
# Install the latest version
atmosenv install latest
# Install version from .atmos-version file
atmosenv install# Switch to a specific version
atmosenv use 1.201.0
# Switch to version from .atmos-version file
atmosenv useCreate a .atmos-version file in your project root:
echo "1.201.0" > .atmos-versionatmosenv will automatically use this version when running atmos commands in this directory.
# List installed versions
atmosenv list
# List available remote versions
atmosenv list-remote
# List more versions
atmosenv list-remote -n 50
# Include pre-release versions
atmosenv list-remote --prereleases# Uninstall a specific version
atmosenv uninstall 1.200.0
# Uninstall without confirmation
atmosenv uninstall -f 1.200.0| Command | Description |
|---|---|
atmosenv install [VERSION] |
Install a specific Atmos version |
atmosenv use [VERSION] |
Switch to a specific version |
atmosenv uninstall VERSION |
Uninstall a specific version |
atmosenv list |
List installed versions |
atmosenv list-remote |
List available versions |
atmosenv version-name |
Print current version |
atmosenv version-file |
Print path to version file |
atmosenv init |
Configure shell environment |
atmosenv help |
Show help message |
| Variable | Default | Description |
|---|---|---|
ATMOSENV_CONFIG_DIR |
~/.config/atmosenv |
Configuration directory |
ATMOSENV_ATMOS_VERSION |
- | Override version selection |
ATMOSENV_AUTO_INSTALL |
true |
Auto-install missing versions |
ATMOSENV_LOG_LEVEL |
INFO |
Log level (DEBUG, INFO, WARN, ERROR) |
atmosenv resolves the Atmos version to use in this order:
ATMOSENV_ATMOS_VERSIONenvironment variable (highest priority).atmos-versionfile in current directory.atmos-versionfile in parent directories (traverses up to root)~/.atmos-versionfile~/.config/atmosenv/versionfile- Latest installed version (fallback)
~/.config/atmosenv/
├── version # Default version file
└── versions/ # Installed versions
├── 1.200.0/
│ └── atmos # Atmos binary
└── 1.201.0/
└── atmos
atmosenv manages Atmos versions by:
- Downloading binaries from GitHub releases to
~/.config/atmosenv/versions/ - Providing a shim (
atmos) that intercepts commands and routes them to the correct version - Reading
.atmos-versionfiles to determine which version to use per-project - Verifying checksums to ensure binary integrity
The shim pattern allows transparent version switching without modifying your PATH for each version.
| Feature | atmosenv | tenv | asdf |
|---|---|---|---|
| Atmos-specific | Yes | Yes | Via plugin |
| Shell-based | Yes | No (Go) | Yes |
.atmos-version |
Yes | Yes | .tool-versions |
| Homebrew | Yes | Yes | Yes |
| Auto-install | Yes | Yes | No |
# Run basic tests
./test/run.sh
# Run all tests including installation tests
ATMOSENV_TEST_INSTALL=true ./test/run.sh
# Run specific test file
./test/run.sh test_basic.shatmosenv/
├── bin/ # User-facing executables
│ ├── atmosenv # Main entry point
│ └── atmos # Wrapper shim
├── lib/ # Shared libraries
│ ├── bashlog.sh # Logging framework
│ ├── helpers.sh # Core utilities
│ └── atmosenv-version-file.sh
├── libexec/ # Subcommand implementations
│ ├── atmosenv-install
│ ├── atmosenv-use
│ ├── atmosenv-list
│ └── ...
├── test/ # Test suite
└── .github/workflows/
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Run tests (
./test/run.sh) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- tfenv - The inspiration for this project
- Cloud Posse - Creators of Atmos
- rbenv - The original version manager pattern
- Pepe Amengual (@jamengual) - Creator of atmosenv