Vix.cpp v2.6.0 is here Read the blog
Vix.cpp/Docs
Vix.cpp

Appearance

vix verify ​

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.

bash
vix verify
1

Overview ​

vix verify is the validation command for Vix package artifacts.

It can verify:

txt
package folders
.vixpkg archives
latest package in dist/
current folder when it contains manifest.json
1
2
3
4

It checks:

txt
manifest.json
vix.manifest.v2 schema fields
payload digest
checksums.sha256
minisign signature
required security metadata in strict mode
1
2
3
4
5
6

The command is read-only.

It does not modify the package.

Usage ​

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

Basic examples ​

bash
# 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Auto-detection ​

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

Resolution order:

txt
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.
1
2
3
4

Example:

bash
vix pack --name blog --version 1.0.0
vix verify
1
2

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

Verify current package folder ​

If you are already inside a package folder:

bash
cd dist/blog@1.0.0
vix verify
1
2

Vix detects:

txt
manifest.json
1

and verifies the current directory.

Verify explicit package folder ​

Use:

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

or:

bash
vix verify -p ./dist/blog@1.0.0
1

This verifies the folder directly.

Verify .vixpkg ​

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

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

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.

.vixpkg requirement ​

Verifying .vixpkg requires:

txt
unzip
1

If unzip is missing or extraction fails, Vix reports:

txt
Unable to extract .vixpkg (need unzip).
1

Install unzip, or verify the folder package instead:

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

Target output ​

Example:

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

Output shape:

txt
vix verify
Target:
  ./dist/blog@1.0.0

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

Verification OK.
1
2
3
4
5
6
7
8
9
10

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

Manifest validation ​

vix verify requires:

txt
manifest.json
1

The manifest must be valid JSON.

The root must be a JSON object.

The manifest schema must be:

txt
vix.manifest.v2
1

Required minimal fields:

txt
schema
package.name
package.version
abi.os
abi.arch
payload.digest_algorithm
payload.digest
1
2
3
4
5
6
7

Minimal manifest shape ​

Example:

json
{
  "schema": "vix.manifest.v2",
  "package": {
    "name": "blog",
    "version": "1.0.0"
  },
  "abi": {
    "os": "linux",
    "arch": "x86_64"
  },
  "payload": {
    "digest_algorithm": "sha256",
    "digest": "..."
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Missing manifest ​

If manifest.json is missing, Vix fails:

txt
manifest.json is missing.
1

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

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

Fix:

bash
vix pack
vix verify
1
2

or:

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

Payload digest verification ​

On Linux and macOS, Vix verifies the payload digest.

The manifest digest is the authoritative value:

json
{
  "payload": {
    "digest": "..."
  }
}
1
2
3
4
5

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

txt
manifest.payload.digest
1

If they differ, verification fails:

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

Payload excludes ​

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

txt
manifest.json
checksums.sha256
meta/payload.digest
meta/payload.digest.minisig
1
2
3
4

If the manifest has:

json
{
  "payload": {
    "excludes": [
      "manifest.json",
      "checksums.sha256",
      "meta/payload.digest",
      "meta/payload.digest.minisig"
    ]
  }
}
1
2
3
4
5
6
7
8
9
10

Vix also applies those excludes.

meta/payload.digest ​

If the package contains:

txt
meta/payload.digest
1

Vix checks that it matches:

txt
manifest.payload.digest
1

If it differs, verification fails:

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

If it is missing:

txt
meta/payload.digest missing.
1

This is a warning by default.

In strict mode, it becomes an error.

Checksums verification ​

On Linux and macOS, Vix verifies:

txt
checksums.sha256
1

unless you pass:

bash
vix verify --no-hash
1

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

txt
file exists
computed sha256 matches expected sha256
1
2

If a listed file is missing, verification fails.

If a hash differs, verification fails.

Missing checksums ​

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

txt
checksums.sha256 is missing.
1

In strict mode, it becomes an error:

txt
checksums.sha256 is missing (strict mode).
1

Skip checksum verification ​

Use:

bash
vix verify --no-hash
1

This skips checksums.sha256 verification.

With --verbose, Vix prints:

txt
checksums verification skipped (--no-hash)
1

Signature verification ​

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

txt
meta/payload.digest
1

The signature file is:

txt
meta/payload.digest.minisig
1

The public key can come from:

txt
--pubkey <path>
VIX_MINISIGN_PUBKEY
default key locations
1
2
3

Public key resolution order ​

Vix resolves the public key in this order:

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

Example:

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

or:

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

Require signature ​

Use:

bash
vix verify --require-signature
1

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

Recommended release verification:

bash
vix verify \
  --path ./dist/blog@1.0.0 \
  --pubkey ./keys/vix-pack.pub \
  --require-signature
1
2
3
4

Strict mode ​

Use:

bash
vix verify --strict
1

Strict mode makes missing optional security metadata fail.

In strict mode, these become errors:

txt
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
1
2
3
4
5

Strict mode is useful for CI and release workflows.

Skip signature verification ​

Use:

bash
vix verify --no-sig
1

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:

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

Missing signature ​

If the signature file is missing:

txt
meta/payload.digest.minisig
1

Vix warns by default:

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

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

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

Signature verification tools ​

Signature verification requires:

txt
minisign
1

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

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

Windows behavior ​

On Windows, the current implementation performs manifest checks only.

In strict mode, Vix warns:

txt
Windows: only manifest checks are implemented for now.
1

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

Exit codes ​

Exit codeMeaning
0Verification OK.
1Verification failed.
bash
vix build --preset release
vix check --tests
vix pack --name blog --version 1.0.0
vix verify --path ./dist/blog@1.0.0
1
2
3
4

If a .vixpkg archive was created:

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

Strict CI flow ​

bash
vix build --preset release
vix check --tests
vix pack --name blog --version 1.0.0
vix verify --path ./dist/blog@1.0.0 --strict
1
2
3
4

Signed release flow ​

Pack with required signing:

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

Verify with required signature:

bash
vix verify \
  --path ./dist/blog@1.0.0 \
  --pubkey ./keys/vix-pack.pub \
  --require-signature
1
2
3
4

or:

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

Auto-detect latest package flow ​

bash
vix pack --name blog --version 1.0.0
vix verify
1
2

This verifies the latest package folder found in:

txt
dist/
1

Options ​

OptionDescription
-p, --path <path>Package folder or .vixpkg artifact. Default: auto-detect.
--pubkey <path>Minisign public key.
--verbosePrint detailed checks and diagnostics.
--strictFail on missing optional security metadata.
--require-signatureFail if signature is missing or cannot be verified.
--no-sigSkip signature verification.
--no-hashSkip checksums.sha256 verification.
-h, --helpShow command help.

Environment variables ​

VariableDescription
VIX_MINISIGN_PUBKEYPublic key path used to verify minisign signatures.

Commands reference ​

CommandDescription
vix verifyAuto-detect and verify a package.
vix verify --verboseAuto-detect and print detailed checks.
vix verify --path ./dist/blog@1.0.0Verify a package folder.
vix verify --path ./dist/blog@1.0.0.vixpkgVerify a .vixpkg archive.
vix verify --strictFail on missing optional security metadata.
vix verify --require-signatureRequire minisign signature verification.
vix verify --no-sigSkip signature verification.
vix verify --no-hashSkip checksum verification.

Common workflows ​

Pack and verify folder ​

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

Pack and verify archive ​

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

Verify latest package automatically ​

bash
vix verify
1

Verify with detailed output ​

bash
vix verify --verbose
1

Verify without checksum check ​

bash
vix verify --no-hash
1

Verify without signature check ​

bash
vix verify --no-sig
1

Verify with required signature ​

bash
vix verify \
  --path ./dist/blog@1.0.0 \
  --pubkey ./keys/vix-pack.pub \
  --require-signature
1
2
3
4

Verify in CI ​

bash
vix build --preset release
vix check --tests
vix pack --name blog --version 1.0.0
vix verify --path ./dist/blog@1.0.0 --strict
1
2
3
4

Common mistakes ​

Verifying before packing ​

Wrong:

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

when the package does not exist.

Correct:

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

Forgetting the public key ​

Wrong:

bash
vix verify --require-signature
1

when no public key is configured.

Correct:

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

or:

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

Using --no-sig with strict verification ​

Wrong:

bash
vix verify --strict --no-sig
1

Correct:

bash
vix verify --strict
1

or:

bash
vix verify --no-sig
1

depending on whether you want strict signature enforcement.

Expecting .vixpkg verification without unzip ​

Verifying a .vixpkg requires:

txt
unzip
1

If unzip is unavailable, verify the package folder:

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

Expecting signature verification without minisign ​

Signature verification requires:

txt
minisign
1

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

Expecting --no-hash to skip payload digest ​

--no-hash skips checksums.sha256 verification.

It does not skip manifest.payload.digest verification.

Expecting Windows to perform all checks ​

The current Windows implementation focuses on manifest checks.

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

Troubleshooting ​

manifest.json is missing ​

Run:

bash
vix pack
1

Then verify again:

bash
vix verify
1

Or pass the correct package path:

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

manifest.json is invalid JSON ​

Open the manifest:

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

Then regenerate the package:

bash
vix pack --name <name> --version <version>
1

manifest.schema must be 'vix.manifest.v2' ​

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

Regenerate it:

bash
vix pack
1

Payload digest mismatch ​

The package contents changed after packing.

Regenerate the package:

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

SHA256 mismatch ​

A file listed in checksums.sha256 changed after packing.

Regenerate the package:

bash
vix pack
1

Missing file listed in checksums.sha256 ​

A file was removed after packing.

Regenerate the package or restore the missing file.

meta/payload.digest.minisig missing ​

The package was not signed.

For signed packages:

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

Then verify:

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

--pubkey is required ​

Provide a public key:

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

or set:

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

minisign verification failed ​

Check that:

txt
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
1
2
3
4

Then repack and verify again.

Unable to extract .vixpkg ​

Install unzip, or verify the package folder instead:

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

Best practices ​

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.

CommandPurpose
vix packCreate a package folder or .vixpkg artifact.
vix cacheStore a verified package locally.
vix buildBuild before packaging.
vix checkValidate before packaging.
vix taskAutomate release workflows.
vix publishPublish a tagged package version to the registry.

Next step ​

Store a verified package locally.

Open the vix cache guide

Released under the MIT License.

Copyright © 2026 Vix.cpp

Morty Proxy This is a proxified and sanitized view of the page, visit original site.