# 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).

## Usage

Execute the `atmos toolchain env` command like this:

```shell
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)

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

Source it directly in your shell:

```shell
eval "$(atmos toolchain env)"
```

### Fish Shell

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

Source it in Fish:

```shell
atmos toolchain env --format fish | source
```

### PowerShell

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

Execute it in PowerShell:

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

### Dotenv Format

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

### JSON Format

```shell
atmos toolchain env --format json
```

Example output:

```json
{
  "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:

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

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

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

### Relative Paths

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

### File Output

Append PATH to a file instead of stdout:

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

```bash
eval "$(atmos toolchain env)"
```

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

```fish
atmos toolchain env --format fish | source
```

**PowerShell** (`$PROFILE`):

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

### CI/CD Integration

**GitHub Actions** (recommended - native integration):

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

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

**GitLab CI**:

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

### Docker Integration

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