vix verify verifies a Vix package folder or .vixpkg artifact against the vix.manifest.v2 package format.

Use it when you want to check that a package created by vix pack is valid, complete, and safe to reuse.

vix verify

vix verify is the validation command for Vix package artifacts.

It can verify:

package folders
.vixpkg archives
latest package in dist/
current folder when it contains manifest.json

It checks:

manifest.json
vix.manifest.v2 schema fields
payload digest
checksums.sha256
minisign signature
required security metadata in strict mode

The command is read-only.

It does not modify the package.

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

# Auto-detect latest package
vix verify

# Verify a package folder
vix verify --path ./dist/blog@1.0.0

# Verify a .vixpkg artifact
vix verify --path ./dist/blog@1.0.0.vixpkg

# Print detailed checks
vix verify --verbose

# Fail on missing optional security metadata
vix verify --strict

When no --path is provided, Vix tries to choose a package automatically.

Resolution order:

1. If current directory contains manifest.json, verify current directory.
2. Else if current directory contains CMakeLists.txt, verify latest dist/*/manifest.json.
3. Else if ./dist exists, verify latest dist/*/manifest.json.
4. Else verify current directory and fail with a useful error if no manifest exists.

Example:

vix pack --name blog --version 1.0.0
vix verify

If dist/blog@1.0.0/manifest.json is the latest package manifest, Vix verifies that package.

If you are already inside a package folder:

cd dist/blog@1.0.0
vix verify

Vix detects:

manifest.json

and verifies the current directory.

Use:

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

or:

vix verify -p ./dist/blog@1.0.0

This verifies the folder directly.

On Linux and macOS, Vix can verify a .vixpkg archive:

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

The archive is extracted to a temporary directory.

Then Vix verifies the extracted package root.

If extraction produces a single nested folder containing manifest.json, Vix automatically uses that nested folder as the package root.

Verifying .vixpkg requires:

unzip

If unzip is missing or extraction fails, Vix reports:

Unable to extract .vixpkg (need unzip).

Install unzip, or verify the folder package instead:

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

Example:

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

Output shape:

vix verify
Target:
  ./dist/blog@1.0.0

payload digest ok
digest: <sha256>
checksums ok: 12 file(s)
signature ok (minisign)

Verification OK.

If auto-detection is used with --verbose, Vix also prints the auto-detected package path.

vix verify requires:

manifest.json

The manifest must be valid JSON.

The root must be a JSON object.

The manifest schema must be:

vix.manifest.v2

Required minimal fields:

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

Example:

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

If manifest.json is missing, Vix fails:

manifest.json is missing.

If no explicit path was provided, Vix also prints hints:

If you are in a project folder, run: vix verify --path ./dist/<name>@<version>
Or run `vix pack` first.

Fix:

vix pack
vix verify

or:

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

On Linux and macOS, Vix verifies the payload digest.

The manifest digest is the authoritative value:

{
  "payload": {
    "digest": "..."
  }
}

Vix rebuilds a stable SHA256 listing of the package payload, computes the digest, and compares it to:

manifest.payload.digest

If they differ, verification fails:

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

To avoid self-referential hashes, these files are excluded from the payload digest:

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

If the manifest has:

{
  "payload": {
    "excludes": [
      "manifest.json",
      "checksums.sha256",
      "meta/payload.digest",
      "meta/payload.digest.minisig"
    ]
  }
}

Vix also applies those excludes.

If the package contains:

meta/payload.digest

Vix checks that it matches:

manifest.payload.digest

If it differs, verification fails:

Payload digest mismatch (meta/payload.digest != manifest.payload.digest).

If it is missing:

meta/payload.digest missing.

This is a warning by default.

In strict mode, it becomes an error.

On Linux and macOS, Vix verifies:

checksums.sha256

unless you pass:

vix verify --no-hash

For each file listed in checksums.sha256, Vix checks:

file exists
computed sha256 matches expected sha256

If a listed file is missing, verification fails.

If a hash differs, verification fails.

If checksums.sha256 is missing, Vix warns by default:

checksums.sha256 is missing.

In strict mode, it becomes an error:

checksums.sha256 is missing (strict mode).

Use:

vix verify --no-hash

This skips checksums.sha256 verification.

With --verbose, Vix prints:

checksums verification skipped (--no-hash)

On Linux and macOS, Vix can verify a minisign signature for:

meta/payload.digest

The signature file is:

meta/payload.digest.minisig

The public key can come from:

--pubkey <path>
VIX_MINISIGN_PUBKEY
default key locations

Vix resolves the public key in this order:

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

Example:

vix verify --pubkey ./keys/vix-pack.pub --require-signature

or:

VIX_MINISIGN_PUBKEY=./keys/vix-pack.pub vix verify --require-signature

Use:

vix verify --require-signature

This fails if the signature is missing or cannot be verified.

Recommended release verification:

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

Use:

vix verify --strict

Strict mode makes missing optional security metadata fail.

In strict mode, these become errors:

missing checksums.sha256
missing meta/payload.digest
missing meta/payload.digest.minisig
missing public key when signature exists or is required
missing minisign when signature is required

Strict mode is useful for CI and release workflows.

Use:

vix verify --no-sig

This skips signature verification.

However, this cannot be combined safely with strict signature requirements.

If you use --no-sig with --require-signature or --strict, Vix fails:

--no-sig cannot be used with --require-signature/--strict.

If the signature file is missing:

meta/payload.digest.minisig

Vix warns by default:

meta/payload.digest.minisig missing (signature not verified).
To generate it, set VIX_MINISIGN_SECKEY when running `vix pack`.

With --require-signature or --strict, this becomes an error:

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

Signature verification requires:

minisign

If minisign is missing and signature is required, Vix fails.

If signature is not required, Vix warns and skips signature verification.

On Windows, the current implementation performs manifest checks only.

In strict mode, Vix warns:

Windows: only manifest checks are implemented for now.

Full payload, checksum, archive extraction, and minisign verification are currently implemented for Unix-like systems.

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

If a .vixpkg archive was created:

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

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

Pack with required signing:

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

Verify with required signature:

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

or:

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

vix pack --name blog --version 1.0.0
vix verify

This verifies the latest package folder found in:

dist/

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

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

vix verify

vix verify --verbose

vix verify --no-hash

vix verify --no-sig

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

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

Wrong:

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

when the package does not exist.

Correct:

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

Wrong:

vix verify --require-signature

when no public key is configured.

Correct:

vix verify --pubkey ./keys/vix-pack.pub --require-signature

or:

VIX_MINISIGN_PUBKEY=./keys/vix-pack.pub vix verify --require-signature

Wrong:

vix verify --strict --no-sig

Correct:

vix verify --strict

or:

vix verify --no-sig

depending on whether you want strict signature enforcement.

Verifying a .vixpkg requires:

unzip

If unzip is unavailable, verify the package folder:

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

Signature verification requires:

minisign

If you do not require signature verification, Vix can still verify manifest, payload digest, and checksums.

--no-hash skips checksums.sha256 verification.

It does not skip manifest.payload.digest verification.

The current Windows implementation focuses on manifest checks.

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

Run:

vix pack

Then verify again:

vix verify

Or pass the correct package path:

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

Open the manifest:

cat ./dist/<name>@<version>/manifest.json

Then regenerate the package:

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

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

Regenerate it:

vix pack

The package contents changed after packing.

Regenerate the package:

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

A file listed in checksums.sha256 changed after packing.

Regenerate the package:

vix pack

A file was removed after packing.

Regenerate the package or restore the missing file.

The package was not signed.

For signed packages:

VIX_MINISIGN_SECKEY=./keys/vix-pack.key \
  vix pack --sign=required

Then verify:

vix verify --pubkey ./keys/vix-pack.pub --require-signature

Provide a public key:

vix verify --pubkey ./keys/vix-pack.pub --require-signature

or set:

export VIX_MINISIGN_PUBKEY=./keys/vix-pack.pub

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 verify again.

Install unzip, or verify the package folder instead:

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

Run vix verify after every release package.

Use --strict in CI.

Use --require-signature for serious release artifacts.

Use --verbose when debugging verification failures.

Do not edit package contents after vix pack.

If package contents change, run vix pack again.

Keep private signing keys secure.

Use VIX_MINISIGN_PUBKEY in CI when verifying signed packages.

Verify the folder package first, then verify the .vixpkg archive when it exists.

Store a verified package locally.

Open the vix cache guide