atmos toolchain env

Export the PATH environment variable for your toolchain tools in shell-specific formats. This command makes it easy to integrate toolchain paths into different shell environments (Bash, Fish, PowerShell) and configuration files (.env, JSON).

When toolchain proxies are configured, this command also creates their command links and exports the private context needed to resolve them after changing directories.

atmos toolchain env --help

Usage

Execute the atmos toolchain env command like this:

atmos toolchain env

By default, the command outputs in Bash/Zsh export format. You can specify different output formats using the --format flag.

Examples

Bash/Zsh (default)

atmos toolchain env
# Output: export PATH='/path/to/tools/bin:/usr/local/bin:/usr/bin:/bin'

Source it directly in your shell:

eval "$(atmos toolchain env)"

This also activates configured proxies, so a proxy such as ls can be used directly in the shell.

Fish Shell

atmos toolchain env --format fish
# Output: set -gx PATH '/path/to/tools/bin' '/usr/local/bin' '/usr/bin' '/bin'

Source it in Fish:

atmos toolchain env --format fish | source

PowerShell

atmos toolchain env --format powershell
# Output: $env:PATH = "/path/to/tools/bin;C:\Windows\System32"

Execute it in PowerShell:

Invoke-Expression (atmos toolchain env --format powershell)

Dotenv Format

atmos toolchain env --format dotenv > .env
# Creates .env file with: PATH='/path/to/tools/bin:/usr/local/bin:/usr/bin:/bin'

JSON Format

atmos toolchain env --format json

Example output:

{
  "tools": [
    {
      "tool": "terraform",
      "version": "1.5.0",
      "path": "/home/user/.tools/terraform/1.5.0/bin"
    }
  ],
  "final_path": "/home/user/.tools/terraform/1.5.0/bin:/usr/local/bin:/usr/bin:/bin",
  "count": 1
}

GitHub Actions (GITHUB_PATH)

Native support for GitHub Actions GITHUB_PATH environment file:

atmos toolchain env --format github

Output (one path per line, compatible with $GITHUB_PATH):

/home/runner/.tools/opentofu/1.7.0/bin
/home/runner/.tools/terraform-docs/0.18.0/bin

When $GITHUB_PATH is set, the github format automatically writes to that file:

- name: Install and configure toolchain
  run: |
    atmos toolchain install
    atmos toolchain env --format github
    # Automatically appends to $GITHUB_PATH

- name: Use tools (next step has updated PATH)
  run: |
    tofu version  # Uses toolchain version

Or explicitly specify the output file:

atmos toolchain env --format github --output $GITHUB_PATH

Relative Paths

atmos toolchain env --relative
# Uses relative paths instead of absolute

File Output

Append PATH to a file instead of stdout:

atmos toolchain env --output /path/to/file
# Shows: ✓ Appended PATH to /path/to/file

This is useful for CI/CD environments that use file-based environment configuration.

Flags

--format, -f (optional)

Output format: bash, fish, powershell, json, dotenv, github

Default: bash

Environment variable: ATMOS_TOOLCHAIN_ENV_FORMAT

--output, -o (optional)

Append output to file instead of stdout. For github format, defaults to $GITHUB_PATH if set.

Environment variable: ATMOS_TOOLCHAIN_ENV_OUTPUT

--relative (optional)

Use relative paths instead of absolute paths

Environment variable: ATMOS_TOOLCHAIN_RELATIVE

Common Use Cases

Shell Integration

Add to your shell profile to automatically use toolchain tools:

Bash/Zsh (~/.bashrc or ~/.zshrc):

eval "$(atmos toolchain env)"

Fish (~/.config/fish/config.fish):

atmos toolchain env --format fish | source

PowerShell ($PROFILE):

Invoke-Expression (atmos toolchain env --format powershell)

CI/CD Integration

GitHub Actions (recommended - native integration):

- name: Install Atmos Toolchain
  run: |
    atmos toolchain install
    atmos toolchain env --format github
    # Automatically appends paths to $GITHUB_PATH

- name: Use toolchain (PATH updated from previous step)
  run: |
    terraform version  # Uses toolchain version

GitHub Actions (legacy - eval in same step):

- name: Setup Atmos Toolchain
  run: |
    atmos toolchain install
    eval "$(atmos toolchain env)"
    terraform version  # Uses toolchain version

GitLab CI:

before_script:
  - eval "$(atmos toolchain env)"

Docker Integration

RUN atmos toolchain env --format dotenv >> /etc/environment

Notes

• The command reads tools from your .tool-versions file
• Only installed tools are included in the PATH
• The generated PATH prepends toolchain paths to your existing PATH
• Each output format is optimized for its target environment:
  • bash: Single-quoted export statement with proper escaping
  • fish: Space-separated paths with set -gx syntax
  • powershell: Double-quoted assignment with PowerShell escaping
  • dotenv: Compatible with .env file parsers
  • json: Structured data for programmatic use
  • github: One path per line, compatible with GitHub Actions $GITHUB_PATH
• The command respects the --toolchain-path flag and ATMOS_TOOLCHAIN_PATH environment variable