Skip to content
CAPA CAPA CAPA Docs

Lockfile and cache

Managed install resolves remote skills, plugins, rules, hooks, and agent snippets once, then records those decisions so later installs stay reproducible and fast.

Lockfile (capabilities.lock)

Section titled “Lockfile (capabilities.lock)”

When you run capa install, capa writes capabilities.lock next to your capabilities file. The lockfile pins resolved refs for remote sources so the next install reuses the same commits/versions instead of floating to whatever main is today.

Treat the lockfile as part of the project: commit it so teammates and CI get the same resolved graph.

Cache

Section titled “Cache”

capa caches remote git sources locally as bare git mirrors (plus file snapshots) so repeated installs do not re-clone from the network every time.

Commands

Section titled “Commands”
Terminal window
capa cache          # show location, size, per-repo breakdown
capa cache clean    # remove all cached repositories and snapshots

Bypass for one install

Section titled “Bypass for one install”
Terminal window
capa install --no-cache

--no-cache bypasses the on-disk cache and lockfile for that run and re-resolves every remote source from scratch. It does not delete the cache; use capa cache clean when you want to free disk space.

Typical loop

Section titled “Typical loop”
  1. Declare remotes in capabilities.yaml (skills, plugins, rules, and so on).
  2. Install with capa install — capa resolves, caches mirrors, and writes capabilities.lock.
  3. Re-install later — capa uses lock pins + cache for speed and stability.
  4. Force a fresh resolve with capa install --no-cache when you intentionally want new upstream content.
  5. Reclaim disk with capa cache clean if mirrors have grown large or look stale.
Section titled “Related”