Skip to main content

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.

atmos toolchain get --help

Usage​

Get Tool Version​

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​

# Get configured Terraform version
atmos toolchain get terraform

# Get configured kubectl version
atmos toolchain get kubectl

# Get configured Helm version
atmos toolchain get helm

Output shows the tool name and configured version:

terraform: 1.9.8

Get All Tool Versions​

# List all configured tool versions
atmos toolchain get

Output shows all tools from .tool-versions:

terraform: 1.9.8
kubectl: 1.28.0
helm: 3.13.0
tflint: 0.44.1

Show All Available Versions​

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

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

Output shows available versions from the registry:

terraform available versions (showing 10 of 150+):
  1.9.8 (configured)
  1.9.7
  1.9.6
  1.9.5
  1.9.4
  1.9.3
  1.9.2
  1.9.1
  1.9.0
  1.8.5

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.

Use plain to print just the bare version string, ideal for shell substitution in scripts and CI. Use json for structured output that includes installation status.

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:

# 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:

# 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:

# 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:

#!/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:

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:

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

Update Workflow​

Check current version before updating:

# 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​

CommandPurposeShows
getVersion information from .tool-versionsConfigured versions (not installation status)
listInstallation status of toolsInstalled tools with sizes and dates
# 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​

CommandPurposeShows
getVersion from .tool-versionsVersion number
whichBinary location on filesystemFull path to executable
# 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:

atmos toolchain get nonexistent-tool

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

Solution: Add the tool first:

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

Empty .tool-versions​

If no .tool-versions file exists:

atmos toolchain get

Returns an error indicating no tool versions are configured.

Solution: Add some tools:

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:

atmos toolchain get unknown-tool --all

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

--format=plain with --all​

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​

Related Documentation​