apm cache

Inspect and maintain the local cache APM uses to avoid redundant network I/O during apm install.

Synopsis

apm cache info
apm cache clean [--force | --yes]
apm cache prune [--days N]

Description

apm cache groups three subcommands that operate on the local cache root. The cache holds two independent stores:

• Git cache — bare repository databases plus per-SHA worktree checkouts, keyed by resolved commit.
• HTTP cache — conditional-GET responses for the GitHub release and API endpoints APM polls during install.

The cache is purely a performance optimization. Removing it never breaks correctness; the next apm install re-fetches whatever it needs.

Subcommands

apm cache info

Show the resolved cache root, per-store entry counts, and a size breakdown.

apm cache info

Output:

[i] Cache root: /Users/you/Library/Caches/apm
  Git repositories (db):    12
  Git checkouts:            34
  HTTP cache entries:       87

  Total size:               142.3 MB
    Git:                    138.1 MB
    HTTP:                   4.2 MB

apm cache clean

Remove every entry from both the git and HTTP caches. Prompts for confirmation unless a skip flag is passed.

apm cache clean              # interactive prompt
apm cache clean --force      # non-interactive
apm cache clean --yes        # alias for --force

Flag	Description
--force, -f	Skip the confirmation prompt.
--yes, -y	Alias for --force. Use in CI scripts so the command never blocks on stdin.

Caution

clean removes every cached commit and every cached HTTP response. The next apm install will re-fetch everything from the network. Use prune when you only want to reclaim space from stale entries.

apm cache prune

Remove git-cache checkouts whose filesystem mtime is older than --days N. Defaults to 30 days. The HTTP cache is not touched.

apm cache prune              # default: older than 30 days
apm cache prune --days 7     # tighter window

Flag	Description
--days N	Remove entries not accessed within this many days. Default: 30.

Lockfile-blind

prune does not consult any project’s apm.lock.yaml before evicting entries. A pinned commit SHA referenced by your lockfile may be pruned if nothing has touched its checkout recently; the next apm install will re-clone it from the remote. Safe, but can surprise air-gapped or rate-limited environments.

Cache layout

The cache root resolves in this precedence order (first match wins):

1. APM_NO_CACHE=1 — per-invocation temp directory, cleaned at exit.
2. APM_CACHE_DIR=/path — explicit override.
3. Platform default:
   • macOS: ~/Library/Caches/apm/
   • Linux: ${XDG_CACHE_HOME:-~/.cache}/apm/
   • Windows: %LOCALAPPDATA%\apm\Cache\

Inside the cache root:

<cache-root>/
  git/
    db_v1/           # bare repository databases
                     #   <shard>/      -- full bare clone (default)
                     #   <shard>__p/   -- partial bare clone
                     #                    (--filter=blob:none) used
                     #                    for sparse-checkout consumers
    checkouts_v1/    # per-SHA worktree checkouts, variant-keyed
                     #   <shard>/<sha>/full/             -- full tree
                     #   <shard>/<sha>/sparse-<hash>/    -- sparse cone
                     #                                     (<hash> = first
                     #                                      16 hex of
                     #                                      sha256(paths))
  http_v1/           # conditional-GET response cache

The full/ and sparse-<variant>/ subdirs let two consumers of the same commit share storage when they want the same subdirs, and keep distinct shards when they do not — without the variant suffix the sparse checkout would clobber the full tree for any other consumer of that SHA.

The cache root is created with mode 0700 and validated to be absolute with no NUL bytes before use.

Environment variables

Variable	Effect
APM_CACHE_DIR	Override the cache root. Must be an absolute path.
APM_NO_CACHE	When set to 1, true, or yes, route all cache I/O to a temp directory cleaned at process exit.
XDG_CACHE_HOME	Honored on Linux and (when explicitly set) macOS.

Coming from npm?

apm cache clean mirrors npm cache clean: it nukes the local cache and forces re-download on next install. There is no --dry-run and no per-package targeting; cleaning is all-or-nothing.

Related

• apm install — populates the cache during dependency resolution.
• Lockfile spec — what gets pinned and re-fetched.