vix cache stores a Vix package locally so it can be reused quickly.

Use it when you already have a package folder or .vixpkg artifact and want to place it in the local Vix package cache.

vix cache --path ./dist/blog@1.0.0

vix cache takes an existing Vix package and stores it in a local cache layout.

It is useful after:

vix pack
vix verify

The command supports:

package folders
.vixpkg artifacts
custom store locations
safe overwrite with --force
verification before caching
signature verification
atomic cache writes

The cached package is stored by:

name
version
ABI tag

The default destination shape is:

<store>/packs/<name>/<version>/<os>-<arch>/

Example:

~/.local/share/vix/packs/blog/1.0.0/linux-x86_64/

vix cache --path <folder|artifact.vixpkg> [options]

--path is required.

# Cache a package folder
vix cache --path ./dist/blog@1.0.0

# Cache a .vixpkg artifact
vix cache --path ./dist/blog@1.0.0.vixpkg

# Overwrite an existing cached package
vix cache --path ./dist/blog@1.0.0 --force

# Show detailed copy operations
vix cache --path ./dist/blog@1.0.0 --verbose

# Cache into a custom store
vix cache --path ./dist/blog@1.0.0 --store ./local-store

You must pass:

--path <folder|artifact.vixpkg>

If you run:

vix cache

Vix reports:

Missing --path. Try: vix cache --path <folder|artifact.vixpkg>

Correct:

vix cache --path ./dist/blog@1.0.0

or:

vix cache --path ./dist/blog@1.0.0.vixpkg

vix cache accepts:

package folder
.vixpkg artifact

A package folder must contain:

manifest.json

A .vixpkg artifact is extracted first, then cached.

On Linux and macOS, .vixpkg extraction uses:

unzip

Example:

vix cache --path ./dist/blog@1.0.0.vixpkg

If unzip is missing or extraction fails, Vix reports:

Unable to extract .vixpkg (need unzip).

In that case, cache the folder package instead:

vix cache --path ./dist/blog@1.0.0

If a .vixpkg extracts to a single nested folder, Vix detects it.

Example extracted layout:

/tmp/vix_cache_1234/
└── blog@1.0.0/
    └── manifest.json

Vix uses:

/tmp/vix_cache_1234/blog@1.0.0/

as the package root.

When caching starts, Vix prints the original input and the resolved package root.

Example output shape:

vix cache

Source:
  dist/blog@1.0.0.vixpkg

Pack root:
  /tmp/vix_cache_1234/blog@1.0.0

For folder packages, the source and pack root are usually the same.

The package root must contain:

manifest.json

If it is missing, Vix reports:

manifest.json is missing in pack.
Make sure you pass a valid package folder or .vixpkg artifact.

Fix:

vix pack --name blog --version 1.0.0
vix cache --path ./dist/blog@1.0.0

vix cache expects a Vix manifest v2 package:

{
  "schema": "vix.manifest.v2",
  "package": {
    "name": "blog",
    "version": "1.0.0"
  },
  "abi": {
    "os": "linux",
    "arch": "x86_64"
  },
  "payload": {
    "digest_algorithm": "sha256",
    "digest": "..."
  }
}

Required fields:

schema
package.name
package.version
abi.os
abi.arch
payload.digest_algorithm
payload.digest

The cache destination is computed from:

manifest.package.name
manifest.package.version
manifest.abi.os
manifest.abi.arch

Example:

{
  "package": {
    "name": "blog",
    "version": "1.0.0"
  },
  "abi": {
    "os": "linux",
    "arch": "x86_64"
  }
}

Destination:

<store>/packs/blog/1.0.0/linux-x86_64/

The ABI tag is:

<os>-<arch>

Example:

linux-x86_64

If --store is not passed, Vix chooses the store root in this order.

On Linux and macOS:

1. VIX_STORE
2. XDG_DATA_HOME/vix
3. ~/.local/share/vix
4. temp/vix fallback

On Windows:

1. VIX_STORE
2. USERPROFILE/.vix
3. temp/vix fallback

So on a normal Linux machine, the default package cache root is usually:

~/.local/share/vix

The final cached package path becomes:

~/.local/share/vix/packs/<name>/<version>/<os>-<arch>/

Use:

vix cache --path ./dist/blog@1.0.0 --store ./local-store

This stores the package under:

./local-store/packs/<name>/<version>/<os>-<arch>/

Example:

./local-store/packs/blog/1.0.0/linux-x86_64/

By default, vix cache verifies the package before storing it.

It checks:

manifest minimal validity
payload digest
checksums.sha256
signature when available or required

This makes caching safer because the package is validated before being copied into the store.

Use:

vix cache --path ./dist/blog@1.0.0 --no-verify

This skips package verification.

Vix prints:

Verification skipped (--no-verify).

This is not recommended for release workflows.

Use it only for local experiments or when the package was already verified in a previous trusted step.

Recommended:

vix verify --path ./dist/blog@1.0.0
vix cache --path ./dist/blog@1.0.0

On Linux and macOS, Vix verifies:

manifest.payload.digest

It rebuilds a stable SHA256 listing of the package payload and compares it to the manifest digest.

If the digest does not match, caching fails.

Example failure:

Payload digest mismatch (computed != manifest.payload.digest).

These files are excluded from the payload digest:

manifest.json
checksums.sha256
meta/payload.digest
meta/payload.digest.minisig

Vix also reads additional excludes from:

{
  "payload": {
    "excludes": []
  }
}

If present, Vix also checks:

meta/payload.digest

against:

manifest.payload.digest

If it differs, caching fails.

If it is missing, Vix warns:

meta/payload.digest missing.

On Linux and macOS, Vix checks:

checksums.sha256

If the file is present, Vix verifies every listed file.

It checks:

file exists
sha256 matches expected value

If a listed file is missing, caching fails.

If a listed file has a different hash, caching fails.

If checksums.sha256 is missing, Vix warns:

checksums.sha256 is missing.

vix cache can verify a minisign signature for:

meta/payload.digest

The signature file is:

meta/payload.digest.minisig

By default, if the signature is missing, Vix warns but does not fail.

To make signature verification mandatory, use:

vix cache \
  --path ./dist/blog@1.0.0 \
  --require-signature \
  --pubkey ./keys/vix-pack.pub

The public key can come from:

--pubkey <path>
VIX_MINISIGN_PUBKEY
~/.config/vix/keys/vix-pack.pub
~/keys/vix/vix-pack.pub

Resolution order:

1. --pubkey <path>
2. VIX_MINISIGN_PUBKEY
3. ~/.config/vix/keys/vix-pack.pub
4. ~/keys/vix/vix-pack.pub

Example with CLI option:

vix cache \
  --path ./dist/blog@1.0.0 \
  --require-signature \
  --pubkey ./keys/vix-pack.pub

Example with environment variable:

VIX_MINISIGN_PUBKEY=./keys/vix-pack.pub \
  vix cache --path ./dist/blog@1.0.0 --require-signature

If the package is not signed and signature is not required, Vix warns:

meta/payload.digest.minisig missing (signature not verified).

If signature is required, Vix fails:

meta/payload.digest.minisig missing (signature required).

If a signature exists but no public key is available, Vix warns by default:

No pubkey provided; skipping signature verification.

If signature is required, Vix fails:

--pubkey is required (or set VIX_MINISIGN_PUBKEY) to verify signature.

If minisign is missing and signature is not required, Vix warns:

minisign not available; skipping signature verification.

If signature is required, Vix fails:

minisign not available (signature required).

vix cache writes the package atomically.

The flow is:

copy package to temporary destination
rename temporary destination to final destination

Example:

<store>/packs/blog/1.0.0/blog-x86_64.tmp.<pid>
<store>/packs/blog/1.0.0/linux-x86_64

This avoids leaving a broken final cache directory if copying fails.

If rename() fails, Vix falls back to copy and remove.

If the package is already cached, Vix refuses to overwrite it by default.

Example error:

Package already cached: <path> (use --force)

Use:

vix cache --path ./dist/blog@1.0.0 --force

This removes the existing cached package and writes the new one.

Use:

vix cache --path ./dist/blog@1.0.0 --verbose

Verbose mode shows detailed operations such as copied files and verification details.

Example output shape:

payload digest ok
digest: <sha256>
checksums ok: 12 file(s)
signature ok (minisign)
copied: manifest.json
copied: include/blog.hpp
copied: src/blog.cpp

Example:

vix cache

Source:
  dist/blog@1.0.0

Pack root:
  /home/user/project/dist/blog@1.0.0

Verifying:
  payload digest ok
  checksums ok: 12 file(s)

Target store:
  /home/user/.local/share/vix

Caching:
  blog@1.0.0 (linux-x86_64)
  /home/user/.local/share/vix/packs/blog/1.0.0/linux-x86_64

Package cached:
  /home/user/.local/share/vix/packs/blog/1.0.0/linux-x86_64

After caching, Vix prints:

Next: vix get blog@1.0.0 --out ./<folder> (coming soon)

vix get is not part of the current cache behavior yet. It is only shown as a future workflow hint.

On Windows, the current implementation performs minimal manifest validation when verification is enabled.

It prints:

Windows: only minimal manifest validation is available right now.

Full payload digest, checksums, .vixpkg extraction, and minisign verification are Unix-oriented in the current implementation.

vix build --preset release
vix check --tests
vix pack --name blog --version 1.0.0
vix verify --path ./dist/blog@1.0.0
vix cache --path ./dist/blog@1.0.0

If a .vixpkg archive exists:

vix cache --path ./dist/blog@1.0.0.vixpkg

Package with signing:

VIX_MINISIGN_SECKEY=./keys/vix-pack.key \
  vix pack --name blog --version 1.0.0 --sign=required

Cache with required signature:

vix cache \
  --path ./dist/blog@1.0.0 \
  --require-signature \
  --pubkey ./keys/vix-pack.pub

vix pack --name blog --version 1.0.0
vix cache --path ./dist/blog@1.0.0 --store ./local-store

Cached path:

./local-store/packs/blog/1.0.0/linux-x86_64/

vix cache --path ./dist/blog@1.0.0
vix cache --path ./dist/blog@1.0.0 --force

Use --force when you intentionally want to replace the cached copy.

vix build --preset release
vix check --tests
vix pack --name blog --version 1.0.0
vix verify --path ./dist/blog@1.0.0
vix cache --path ./dist/blog@1.0.0

For signed CI artifacts:

vix build --preset release
vix check --tests

VIX_MINISIGN_SECKEY=./keys/vix-pack.key \
  vix pack --name blog --version 1.0.0 --sign=required

vix cache \
  --path ./dist/blog@1.0.0 \
  --require-signature \
  --pubkey ./keys/vix-pack.pub

vix pack --name blog --version 1.0.0
vix verify --path ./dist/blog@1.0.0
vix cache --path ./dist/blog@1.0.0

vix cache --path ./dist/blog@1.0.0.vixpkg

vix cache --path ./dist/blog@1.0.0 --force

vix cache \
  --path ./dist/blog@1.0.0.vixpkg \
  --require-signature \
  --pubkey ./keys/vix-pack.pub

vix cache \
  --path ./dist/blog@1.0.0 \
  --store ./local-store

vix cache \
  --path ./dist/blog@1.0.0 \
  --no-verify

Wrong:

vix cache

Correct:

vix cache --path ./dist/blog@1.0.0

Wrong:

vix cache --path ./dist/blog@1.0.0

when the package does not exist.

Correct:

vix pack --name blog --version 1.0.0
vix cache --path ./dist/blog@1.0.0

Wrong:

vix cache --path .

from a normal project root without manifest.json.

Correct:

vix pack
vix cache --path ./dist/<name>@<version>

vix cache does not build.

Build first:

vix build --preset release

Then pack:

vix pack --name blog --version 1.0.0

Then cache:

vix cache --path ./dist/blog@1.0.0

vix cache stores an existing package.

It does not create the package.

Use:

vix pack

to create one.

Avoid this for releases:

vix cache --path ./dist/blog@1.0.0 --no-verify

Prefer:

vix verify --path ./dist/blog@1.0.0
vix cache --path ./dist/blog@1.0.0

Wrong:

vix cache --path ./dist/blog@1.0.0 --require-signature

if no public key is configured.

Correct:

vix cache \
  --path ./dist/blog@1.0.0 \
  --require-signature \
  --pubkey ./keys/vix-pack.pub

or:

VIX_MINISIGN_PUBKEY=./keys/vix-pack.pub \
  vix cache --path ./dist/blog@1.0.0 --require-signature

If the package is already cached, use:

vix cache --path ./dist/blog@1.0.0 --force

only when you intentionally want to overwrite it.

Pass a package folder or .vixpkg:

vix cache --path ./dist/blog@1.0.0

Check that the path exists:

ls ./dist

Then run:

vix cache --path ./dist/<name>@<version>

Install unzip, or cache the folder package:

vix cache --path ./dist/<name>@<version>

You passed a folder that is not a package folder.

Run:

vix pack

Then cache the generated folder:

vix cache --path ./dist/<name>@<version>

Regenerate the package:

vix pack --name <name> --version <version>

Then cache again.

The package was not created with the expected Vix manifest v2 format.

Regenerate it:

vix pack

The package contents changed after packing.

Regenerate and cache again:

vix pack --name <name> --version <version>
vix cache --path ./dist/<name>@<version> --force

A file listed in checksums.sha256 changed.

Regenerate the package:

vix pack

A file was removed after packing.

Regenerate the package or restore the missing file.

Use:

vix cache --path ./dist/<name>@<version> --force

only if replacing the cached package is intentional.

Run with verbose output:

vix cache --path ./dist/<name>@<version> --verbose

Check permissions for the target store directory.

Check that:

the package was signed with the matching private key
the public key is correct
meta/payload.digest was not modified
meta/payload.digest.minisig was not modified

Then repack and cache again.

Run vix verify before vix cache.

Keep verification enabled by default.

Use --require-signature for serious release artifacts.

Use --force only when intentionally replacing a cached package.

Use --store in CI when you want an isolated cache.

Use VIX_STORE when you want a stable shared cache path.

Do not edit package contents after vix pack.

If package contents change, run vix pack again.

Use --verbose when debugging cache failures.

Continue with registry management.

Open the vix registry guide