Atmos Cache

Use this skill for Atmos cache behavior. There are two distinct cache surfaces: CI cache and Terraform registry cache.

Related Skills

Need	Load
Native CI workflows	atmos-ci
Tool versions installed into cache roots	atmos-toolchain
Terraform component execution	atmos-terraform

CI Cache

The CI cache restores and saves the Atmos XDG cache root, including toolchain installs and other known cache directories. GitHub Actions is the supported CI provider today.

ci:
  cache:
    enabled: true
    auto: true
    paths:
      - .terraform
    key: atmos-${{ runner.os }}-${{ hashFiles('**/.tool-versions') }}
    restore_keys:
      - atmos-${{ runner.os }}-

Commands:

Command	Purpose
atmos ci cache paths	Print cache key, paths, and restore keys for actions/cache
atmos ci cache restore	Restore the well-known cache directory
atmos ci cache save	Save the well-known cache directory
atmos ci cache list	List CI cache entries
atmos ci cache delete <key>	Delete a CI cache entry

Use cloudposse/atmos/actions/cache@v1 when the workflow wants a composite action wrapper around Atmos cache behavior. Otherwise use atmos ci cache paths with actions/cache.

Terraform Registry Cache

atmos terraform cache manages the Atmos Terraform registry cache. It is not Terraform's provider plugin cache (TF_PLUGIN_CACHE_DIR).

Commands:

Command	Purpose
atmos terraform cache list	List cached providers/modules
atmos terraform cache mirror	Pre-seed provider artifacts for multiple platforms
atmos terraform cache stats	Show cache size and object counts
atmos terraform cache prune	Remove stale metadata
atmos terraform cache delete <key>	Delete a cached object
atmos terraform cache trust	Trust the cache proxy certificate
atmos terraform cache untrust	Remove the trusted certificate

Use mirror before offline or high-fanout CI runs that need predictable provider availability. Use --all, --components, or --query filters when warming only part of the project.

Guidance

• Do not conflate CI cache, Terraform registry cache, and Terraform plugin cache.
• Prefer cache keys that include Atmos/toolchain config and lock files.
• Keep cache restores before toolchain-heavy steps and saves after all Atmos commands complete.
• Treat toolchain cache warming as an optimization after atmos ci cache restore, not as required correctness. Declared dependencies.tools still auto-install when the owning operation runs.
• For private registry or GitHub reads, solve auth first with Atmos Auth or github/sts; cache should not be used as an auth workaround.