Skip to main content

atmos toolchain clean

Remove all installed CLI tools from your toolchain to free up disk space or start fresh with a clean environment. This gives you a fresh slate for managing tool dependencies across your components and workflows.

atmos toolchain clean --help

Usage​

Execute the atmos toolchain clean command like this:

atmos toolchain clean

Examples​

Clean All Tools​

atmos toolchain clean

Example output:

Cleaning toolchain...
  Removed: hashicorp/terraform@1.9.8 (85.2 MB)
  Removed: opentofu/opentofu@1.10.3 (92.1 MB)
  Removed: kubernetes-sigs/kubectl@1.28.0 (48.5 MB)

Cleaned 3 tools, freed 225.8 MB

Clean with Confirmation Skip​

atmos toolchain clean --force

Skips the confirmation prompt and immediately removes all tools.

Clean Cache Only​

atmos toolchain clean --cache-only

Removes downloaded archives and registry cache without removing installed tools.

Flags​

--force (optional)

Skip confirmation prompt and immediately clean all tools.

Environment variable: ATMOS_TOOLCHAIN_FORCE

--cache-only (optional)

Only clean the download cache, not installed tools. Useful for freeing space while keeping tools ready to use.

Environment variable: ATMOS_TOOLCHAIN_CACHE_ONLY

--dry-run (optional)

Show what would be cleaned without actually removing anything.

Environment variable: ATMOS_TOOLCHAIN_DRY_RUN

What Gets Cleaned​

The clean command removes:

DirectoryContentsPurpose
.tools/bin/Installed tool binariesExecutable files
~/.cache/atmos/toolchain/downloads/Downloaded archivesCached .tar.gz, .zip files
~/.cache/atmos/toolchain/registries/Registry dataCached registry YAML files
~/.cache/atmos/toolchain/temp/Temporary filesExtraction workspace

Use Cases​

Free Up Disk Space​

When disk space is limited, clean unused tools:

# Check current usage
atmos toolchain du

# Clean everything
atmos toolchain clean

# Reinstall only what you need
atmos toolchain install

Start Fresh​

Reset your toolchain after configuration changes:

# Clean all tools
atmos toolchain clean

# Update .tool-versions
atmos toolchain add terraform@1.9.8
atmos toolchain add kubectl@1.28.0

# Install fresh
atmos toolchain install

Clean Corrupted Downloads​

If tool installations fail, clear the cache:

# Clear download cache
atmos toolchain clean --cache-only

# Retry installation
atmos toolchain install terraform@1.9.8

Preview Before Cleaning​

See what would be removed:

# Dry run to see impact
atmos toolchain clean --dry-run

# If satisfied, actually clean
atmos toolchain clean

Notes​

  • The .tool-versions file is not modified by this command
  • After cleaning, run atmos toolchain install to reinstall tools from .tool-versions
  • Use atmos toolchain du before cleaning to see current disk usage
  • The --cache-only flag is useful when you want to free space but keep tools ready