Skip to main content

envy cache

Report where the cache lives and what is using space in it, or change which cache this project uses. The report is one row per installed package variant, one per cached envy deployment, and one per remaining top-level directory, largest first, with a total.

There is no envy cache clean. Everything in the cache is reconstructible from the manifest, so reclaiming space is rm -rf on whatever row you no longer want. That can be one package entry, a whole identity, or the entire root. The next install rebuilds what the project needs.

Usage​

envy cache [--root | --user-wide-root | --local | --shared]
FlagEffect
(none)Print the usage report, with the winning precedence tier named.
--rootPrint the resolved cache root and nothing else. No disk scan.
--user-wide-rootPrint the user-wide cache root and nothing else. That is the tree a project-local checkout reads to find an already-downloaded envy binary, and the only place shell hooks live.
--localUse this project's own tree from now on.
--sharedUse the user-wide cache from now on.

The flags are mutually exclusive, so one invocation performs one action.

Reading the root​

--root prints one line on stdout and skips the usage walk, which makes it the right thing to script against:

$ envy cache --root
/Users/you/src/firmware/out/.envy

The bare report names the tier that decided, because the failure mode worth catching is two things disagreeing about where the cache is:

$ envy cache | head -1
Cache: /Users/you/src/firmware/out/.envy  (@envy cache-local)

The suffix is one of (--cache-root/ENVY_CACHE_ROOT), (recorded by 'envy cache'), (@envy cache-mode), (@envy cache-local), or (default).

--user-wide-root answers the other question, which only differs for a project on its own tree:

$ envy cache --root
/Users/you/src/firmware/out/.envy
$ envy cache --user-wide-root
/Users/you/Library/Caches/envy

A local project reads the second tree for one thing, an envy binary it would otherwise re-download, and never writes to it. See The Cache.

Changing the mode​

--local and --shared record your choice as a zero-byte marker file beside the manifest, .envy-cache-local or .envy-cache-shared, which outranks whatever the manifest declares:

$ envy cache --shared
Cache: /Users/you/Library/Caches/envy  (recorded by 'envy cache')
Previous: /Users/you/src/firmware/out/.envy (no longer used; remove it when convenient)

The marker exists only when your choice differs from the project's own default, so asking for the default clears it rather than restating it. Neither flag moves an existing tree: relocating a multi-GB cache is slow and would race any other envy process holding a lock, so the old root is named and deleting it is your call. Both need a discoverable manifest, and they honor --project like every other manifest-aware command.

Both also deploy envy into the tree the project is about to use rather than the one still recorded, so envy cache --shared on a fresh clone costs no download when you already have that version, and leaves no binary behind in the tree it is abandoning.

Precedence​

The root honors the full chain: --cache-root or ENVY_CACHE_ROOT (which must be absolute), then a marker file, then @envy cache-mode, then @envy cache-local being present at all, then the platform default: ~/Library/Caches/envy on macOS, $XDG_CACHE_HOME/envy or ~/.cache/envy on Linux, %LOCALAPPDATA%\envy on Windows. Directive paths are relative literals anchored to the manifest's directory, never the working directory. envy reads them out of the manifest as text, so a broken manifest above your working directory cannot stop the report. Under --cache-root it does not read a manifest at all.

Measurement is a parallel walk using native directory enumeration. Sizes are apparent file sizes, and symlinked trees are excluded so nothing is double-counted.

Output​

Cache: /Users/you/Library/Caches/envy  (default)

Packages:
  envy.python@r1/darwin-arm64-blake3-f92708b498a20257  257.25MB
  envy.cmake@r0/darwin-arm64-blake3-49a9b2620de8c380   240.93MB
  envy.ninja@r0/darwin-arm64-blake3-268bff6f91bfacc4     2.14MB

Envy deployments:
  0.2.0                                                  8.23MB
  0.1.9                                                  5.72MB

Other:
  specs                                                202.78KB
  shell                                                 22.66KB
  locks                                                      0B

  TOTAL                                                514.36MB

Package rows are identity/platform-arch-blake3-hash, one per option variant. That is why two pythons can appear under one identity, and why bumping an option leaves the old tree behind until you delete it. Envy deployment rows are the versions your projects have pinned over time. Other is everything else the cache holds, such as downloaded specs, shell hooks, and lock files, listed so the total reconciles.

Examples​

To find out what is using disk​

envy cache

Rows are sorted largest first within each section.

To confirm which cache root is in effect​

envy cache --root
# /Users/you/Library/Caches/envy
envy --cache-root /opt/envy-cache cache --root
# /opt/envy-cache

Use the bare report when you want to know why it is what it is:

envy cache | head -1
# Cache: /Users/you/src/firmware/out/.envy  (@envy cache-local)

To delete one package and let envy rebuild it​

rm -rf "$(envy cache --root)/packages/envy.cmake@r0"
envy install

Nothing outside the cache points into it by absolute path, so the only cost is re-downloading.

To reclaim everything​

rm -rf "$(envy cache --root)"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\envy"

This deletes installed packages, cached envy versions, and downloaded specs. The next install in any project restores what that project needs, and the committed bin directory is untouched either way.

To keep a project's packages inside the project​

envy cache --local
envy install

Everything the project downloads now lives under its own tree, so deleting the project reclaims all of it. envy cache --shared puts you back on the user-wide cache. Neither command copies anything, and the next install populates the new root. The wrappers in the bin directory need no attention: they resolve their package at call time, so they follow the cache root without being rewritten.

To retire old envy versions only​

CACHE="$(envy cache --root)"
rm -rf "$CACHE/envy/0.1.9"

This keeps package builds intact while dropping envy binaries no project pins.

See also​