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.

SKILL.md