# atmos toolchain get

Display version information for tools configured in your `.tool-versions` file. View the currently configured version or browse all available versions from the registry.

## Usage

### Get Tool Version

```shell
atmos toolchain get [tool]
```

When a tool name is provided, displays the version configured in `.tool-versions` for that specific tool.

When no tool name is provided, displays versions for all tools in `.tool-versions`.

## Examples

### Get Specific Tool Version

```shell
# Get configured Terraform version
atmos toolchain get terraform

# Get configured kubectl version
atmos toolchain get kubectl

# Get configured Helm version
atmos toolchain get helm
```

The default table shows configured versions, installation status, and the default version. For a bare version suitable for scripts, use `atmos toolchain get terraform --format=plain`.

### Get All Tool Versions

```shell
# List all configured tool versions
atmos toolchain get
```

The default output groups version tables by the names recorded in `.tool-versions`, preserving aliases. Use `--format=plain` for one `tool version` line per configured entry, sorted by those names:

```shell
atmos toolchain get --format=plain
```

```text
hashicorp/terraform 1.9.8
helm/helm 3.13.0
```

Use `atmos toolchain get --format=json` for an array of tool objects, each containing `tool`, `version`, and `installed`. Aggregate output preserves each configured name in `tool`, so an alias and its canonical name remain distinct entries. A named-tool query returns a single object with the canonical tool name.

### Show All Available Versions

```shell
# Show all available versions for a tool
atmos toolchain get terraform --all

# Limit number of versions displayed
atmos toolchain get terraform --all --limit 20
```

The table marks the default version and installation status. Omit the tool name to query available versions for every tool in `.tool-versions`; `--limit` applies to each tool. With `--all --format=json`, each object contains `tool`, `default_version`, and a `versions` array.

## Arguments

- **`tool` (optional)** — Name of the tool to get version information for. Can be the short name (alias) or full `owner/repo` format.

  Examples: `terraform`, `kubectl`, `hashicorp/terraform`, `kubernetes-sigs/kubectl`

  If omitted, displays versions for all tools in `.tool-versions`.

## Flags

- **`--all` (optional)** — Show all available versions from the registry, not just the configured version.

  Useful for discovering which versions are available to install.

  Environment variable: `ATMOS_TOOLCHAIN_ALL`
- **`--limit` (optional)** — Maximum number of versions to display when using `--all`. Default: `10`

  Environment variable: `ATMOS_TOOLCHAIN_LIMIT`
- **`--format`, `-f` (optional)** — Output format: `table` (default), `plain`, or `json`.

  For a named tool, `plain` prints the bare version string for shell substitution. Without a tool name, it prints one `tool version` line per configured entry, preserving aliases.
  Use `json` for structured output that includes installation status: an object for one tool, or an array when the tool name is omitted.

  `plain` cannot be combined with `--all`, since there's no single version to print — use `json` instead.

  Environment variable: `ATMOS_TOOLCHAIN_GET_FORMAT`

## Use Cases

### Check Configured Version

Verify which version is configured before running commands:

```shell
# Check Terraform version before deployment
atmos toolchain get terraform

# Verify kubectl version before cluster operations
atmos toolchain get kubectl
```

### Compare with Available Versions

See if newer versions are available:

```shell
# Show latest Terraform versions
atmos toolchain get terraform --all --limit 5

# Browse available OpenTofu versions
atmos toolchain get opentofu --all
```

### Audit Tool Versions

Review all configured tool versions:

```shell
# Display all tool versions
atmos toolchain get

# Export to file for documentation
atmos toolchain get > tool-versions.txt
```

### Script Integration

Use `--format=plain` to get just the bare version string, no parsing required:

```shell
#!/bin/bash

# Get configured Terraform version
TF_VERSION=$(atmos toolchain get terraform --format=plain)

echo "Using Terraform version: $TF_VERSION"
```

This is the preferred way to capture a version in CI, for example writing to `GITHUB_OUTPUT`:

```shell
version=$(atmos toolchain get vale-cli/vale --format=plain)
echo "version=$version" >> "$GITHUB_OUTPUT"
```

Use `--format=json` when a script needs more than the version, such as installation status:

```shell
atmos toolchain get terraform --format=json | jq -r '.version'
```

### Update Workflow

Check current version before updating:

```shell
# Check current version
atmos toolchain get terraform

# View available versions
atmos toolchain get terraform --all --limit 10

# Update to newer version
atmos toolchain add terraform@1.9.8
```

## Comparison with Related Commands

### `atmos toolchain get` vs `atmos toolchain list`

| Command | Purpose | Shows |
|---------|---------|-------|
| `get` | Version information from `.tool-versions` | Configured versions (not installation status) |
| `list` | Installation status of tools | Installed tools with sizes and dates |

```shell
# Get shows configured versions
atmos toolchain get terraform
# Output: terraform: 1.9.8

# List shows installation details
atmos toolchain list
# Output: Table with installation status, size, date
```

### `atmos toolchain get` vs `atmos toolchain which`

| Command | Purpose | Shows |
|---------|---------|-------|
| `get` | Version from `.tool-versions` | Version number |
| `which` | Binary location on filesystem | Full path to executable |

```shell
# Get shows version
atmos toolchain get terraform
# Output: terraform: 1.9.8

# Which shows path
atmos toolchain which terraform
# Output: /path/to/.tools/bin/hashicorp/terraform/1.9.8/terraform
```

## Error Handling

### Tool Not in .tool-versions

If the tool is not configured:

```shell
atmos toolchain get nonexistent-tool
```

Returns an error indicating the tool is not found in `.tool-versions`.

**Solution**: Add the tool first:

```shell
atmos toolchain add nonexistent-tool@1.0.0
atmos toolchain get nonexistent-tool
```

### Empty .tool-versions

If no `.tool-versions` file exists:

```shell
atmos toolchain get
```

Returns an error indicating no tool versions are configured.

**Solution**: Add some tools:

```shell
atmos toolchain add terraform@1.9.8
atmos toolchain add kubectl@1.28.0
```

### Tool Not in Registry

If requesting all versions for a tool not in the registry:

```shell
atmos toolchain get unknown-tool --all
```

Returns an error indicating the tool is not found in any registry.

### `--format=plain` with `--all`

```shell
atmos toolchain get terraform --all --format=plain
```

Returns an error, since `--all` lists multiple versions and there's no single version to print in
plain format. Use `--format=json` instead.

## Related Commands

- [`atmos toolchain list`](/cli/commands/toolchain/list) - List installed tools with details
- [`atmos toolchain which`](/cli/commands/toolchain/which) - Show path to tool binary
- [`atmos toolchain add`](/cli/commands/toolchain/add) - Add tool to `.tool-versions`
- [`atmos toolchain registry search`](/cli/commands/toolchain/registry/registry-search) - Search for available tools

## Try it out

### toolchain

Copy the example into a new directory and make it your own:

```shell
atmos init examples/toolchain
cd toolchain
```

Read the jq version pinned in .tool-versions.

```shell
atmos toolchain get jq
```

- [Installation guide](/install)
- [Explore the example](/examples/toolchain)
- [Initialization and repository settings](/cli/commands/init#examples-and-source-directories)

## Related Documentation

- [Toolchain Overview](/cli/commands/toolchain/usage) - Complete toolchain documentation
- [Version Management](/cli/commands/toolchain/usage#version-management) - Managing tool versions