Try packslip locally

Start here if you are new to packslip. You will verify a published release, then create, sign, and verify one of your own with a local key, and watch a modified file fail verification.

To install a tool, see Bootstrap a tool. To check files you already downloaded, see Verify a release.

Install packslip

The commands on this page use a POSIX shell. On Windows, run them in WSL and install packslip there as on Linux.

With mise, run mise use -g packslip. Otherwise, on Linux or macOS, run the install script:

curl -fsSL https://packslip.sh | sh

If the script prints an export PATH=... line, run it. packslip version then prints the installed release.

Install packslip lists every method. The APT and RPM packages leave out the publishing commands; install packslip another way. On a platform without a release build, such as an Intel Mac, build from source.

Verify a published release

The hk project attaches a packslip, a signed release bundle named packslip.sigstore.json, to its GitHub releases. Download the bundle from hk 2.8.0 and one of its archives, then verify the archive:

curl -fLO https://github.com/jdx/hk/releases/download/v2.8.0/packslip.sigstore.json
curl -fLO https://github.com/jdx/hk/releases/download/v2.8.0/hk-x86_64-unknown-linux-gnu.tar.gz
packslip verify packslip.sigstore.json --artifact hk-x86_64-unknown-linux-gnu.tar.gz

packslip verify itself downloads nothing. It prints:

ok: github.com/jdx/hk 2.8.0 published 2026-10-20T19:21:05.952758937Z signed by https://github.com/jdx/hk/.github/workflows/release.yml@refs/tags/v2.8.0 (sigstore-oidc) logged 2026-10-20T19:21:06Z (1 of 7 artifact(s) and 0 of 5 asset(s) checked, provenance linked, 7 resource(s))
  repository https://github.com/jdx/hk (id 922514152), owner https://github.com/jdx (id 216188)
  requires hk-aarch64-apple-darwin.tar.gz: libs none
  requires hk-aarch64-unknown-linux-gnu.tar.gz: libs none
  requires hk-aarch64-unknown-linux-musl.tar.gz: libs none
  requires hk-x86_64-unknown-linux-gnu.tar.gz: libs none
  requires hk-x86_64-unknown-linux-musl.tar.gz: libs none
  requires hk-aarch64-pc-windows-msvc.zip: libs combase.dll vcruntime140.dll
  requires hk-x86_64-pc-windows-msvc.zip: libs combase.dll vcruntime140.dll vcruntime140_1.dll

You passed no trust flags, so verify derives the policy from the project the bundle names, github.com/jdx/hk. The signature must come from GitHub Actions, in a certificate that records github.com/jdx/hk as its source repository.

Understand the result explains the rest of the ok: line. How trust works explains what a project name says about the signer and when to add a signer fingerprint.

Create a sample release

The rest of this page runs offline. It signs with a local Ed25519 key instead of a CI identity, and keeps the test signature out of Rekor, Sigstore's public transparency log. Publish a real release explains what to change for a logged release.

Run the commands in an empty directory. They also need tar, but no platform-specific compiler.

mkdir -p staging/bin dist
printf '#!/bin/sh\nprintf "hello from mytool\\n"\n' > staging/bin/mytool
chmod +x staging/bin/mytool
tar -czf dist/mytool-1.2.3.tar.gz -C staging bin
packslip keygen --out release.key

You now have dist/mytool-1.2.3.tar.gz, an archive with one executable at bin/mytool. keygen wrote a signing key pair, release.key and release.pub, and printed its key ID (yours will differ):

wrote release.key and release.pub (key id 8270AD3B51601889)

release.key is the secret key; keep it out of source control. Consumers need only the public key, release.pub. The key ID names the signer in later output. keygen refuses to overwrite an existing key, so to rerun the walkthrough, use a new empty directory.

Create and sign the packslip

packslip create \
  --project mytool.example.com \
  --version 1.2.3 \
  --key release.key --no-log \
  --out dist \
  --url-base https://mytool.example.com/v1.2.3 \
  --bin mytool \
  dist/mytool-1.2.3.tar.gz:any

create hashes the archive and finds the executable inside it. It describes the release in a JSON statement, signs the statement with your key, and writes the signed bundle to dist/packslip.sigstore.json:

wrote dist/packslip.sigstore.json (1 artifact(s), signed by 8270AD3B51601889, unlogged)

Warning: Without --no-log, create records a key-signed signature in Rekor's public log. Keep --no-log for test signatures like this one.

For a fuller release, create also prints a resource count, repackager-attested for a repackager's bundle, and a requires line for each artifact with host requirements.

Read the signed statement

packslip show decodes and prints the statement inside the bundle. It does not check the signature; the next step does.

packslip show dist/packslip.sigstore.json

The statement's core fields, with the sha256 digest abbreviated:

{
  "subject": [{
    "name": "mytool-1.2.3.tar.gz",
    "digest": { "sha256": "..." }
  }],
  "predicateType": "https://packslip.dev/release/v1",
  "predicate": {
    "project": "mytool.example.com",
    "version": "1.2.3",
    "artifacts": [{
      "name": "mytool-1.2.3.tar.gz",
      "url": "https://mytool.example.com/v1.2.3/mytool-1.2.3.tar.gz",
      "format": "tar.gz",
      "bin": ["bin/mytool"]
    }]
  }
}
FieldWhat the consumer does with it
subjectChecks the downloaded file against its signed digest.
predicateTypeRecognizes the payload as a packslip release statement.
project and versionConfirms that this is the requested project and release.
artifacts[].nameConnects the artifact metadata to its entry in subject.
url and formatFinds the file and determines how to unpack it.
binFinds the executable at its actual archive path.

The full output also has a sha512 digest, the artifact's size, the publication time, the signing identity (scheme and key_id), and the in-toto _type. The surrounding bundle, not the statement, carries the signature and verification material.

Verify the archive

packslip verify dist/packslip.sigstore.json \
  --pubkey release.pub --allow-unlogged \
  --artifact dist/mytool-1.2.3.tar.gz

On success it prints one line (your key ID and time will differ):

ok: mytool.example.com 1.2.3 published 2026-10-21T20:22:49.794836741Z signed by 8270AD3B51601889 (sigstore-key) unlogged (1 of 1 artifact(s) checked)

A successful exit means the bundle and the supplied archive both passed. Without --artifact, the line ends (0 of 1 artifact(s) checked): the bundle was checked, but the archive was not.

Without --allow-unlogged, verify refuses this bundle:

verification failed: bundle has no transparency log entry; pass --allow-unlogged to accept one

Warning: --allow-unlogged is an exception for offline tests. Never add it to a real release's verification to work around a failure.

Compare the project and version in the ok: line with the release you expected: your key authenticates the bundle, but verify does not know what you expected. Understand the result lists what a successful check does and does not establish.

To see a failure, change the archive and verify again:

printf x >> dist/mytool-1.2.3.tar.gz
packslip verify dist/packslip.sigstore.json \
  --pubkey release.pub --allow-unlogged \
  --artifact dist/mytool-1.2.3.tar.gz

It exits with status 1 and names the mismatch (your digests will differ):

verification failed: artifact mytool-1.2.3.tar.gz: sha256 is 812e915afcad577787a94fbfe89da7ceea4beef134d915262e13fdf2a59f6943, document says 1f72b5add6abc8a973ac11519d006a75863a8febb5361892223a183e9f6bd227

Publish a real release

For a release people install, record the signature in Rekor, which needs network access: drop --no-log from create and --allow-unlogged from verify. Sign in CI, not with a key on your machine.

To adapt the example to your own files, see Describe your artifacts.