Reference

CLI Reference

Complete reference for the epack command-line interface. Build, sign, verify, and inspect evidence packs from your terminal.

Quick Reference

Build & Sign

# Build a pack
epack build out.epack ./files --stream org/stream

# Sign with keyless (opens browser)
epack sign out.epack

# Sign in CI/CD
EPACK_OIDC_TOKEN=$TOKEN epack sign out.epack

Verify & Inspect

# Verify with identity check
epack verify evidence.epack \
  --issuer "https://accounts.google.com" \
  --subject "security@company.com"

# Inspect pack contents
epack inspect evidence.epack

Common Workflows

These are the most common command sequences for working with evidence packs.

📦

Build → Sign → Verify

The standard evidence pack lifecycle for creating trusted artifacts.

1 build → 2 sign → 3 verify
🔧

Project Setup

Initialize a new epack project with collectors and tools.

1 new → 2 install → 3 collect
🔍

Audit & Compare

Review pack contents and compare against previous versions.

1 verify → 2 inspect → 3 diff

Global Flags

These flags can be used with any command.

Flag Description Default
-q, --quiet Suppress non-essential output. Only errors and primary results are shown. false
--json Output in JSON format for machine consumption. Supported by most commands. false
--no-color Disable colored output. Also respects NO_COLOR env var. false
-v, --verbose Verbose output with additional details for debugging. false
--no-redact Disable secret redaction in error messages. Use with caution false
--ci CI mode: disable spinners, add timestamps. Auto-detected from CI or GITHUB_ACTIONS env vars. false

Environment Variables

Configure epack behavior through environment variables. Command-line flags take precedence.

Variable Description Used By
EPACK_OIDC_TOKEN Optional OIDC identity token for keyless signing outside GitHub Actions ambient OIDC. sign
EPACK_NO_REDACT Set to any value to disable secret redaction in error messages. All commands
NO_COLOR Standard variable to disable colored output (any value). All commands
EPACK_CACHE_DIR Directory for caching downloaded collectors and tools. sync, install

Configuration Precedence

  1. Command-line flags (highest priority)
  2. Environment variables
  3. Project config (epack.yaml)
  4. User config (~/.config/epack/config.yaml)

Exit Codes

Use these exit codes in scripts and CI/CD pipelines to handle different outcomes.

Code Name Description
0 Success Command completed successfully.
1 General Error Generic failure (invalid input, runtime error, etc.).
2 Malformed Pack Pack file cannot be opened or parsed.
10 Lock Invalid Lockfile missing, invalid, or mismatched.
11 Digest Mismatch Binary or artifact digest doesn't match expected value.
12 Signature Mismatch Sigstore signature verification failed.
13 Timeout Operation timed out.
14 Missing Binary Required binary not found or installed.
15 Network Error Network error during fetch operation.
Example: CI/CD error handling 
#!/bin/bash
epack verify evidence.epack --issuer "https://token.actions.githubusercontent.com"
case $? in
  0) echo "Verification passed" ;;
  2) echo "Pack is corrupted or invalid"; exit 1 ;;
  11) echo "Digest mismatch"; exit 1 ;;
  12) echo "Signature verification failed"; exit 1 ;;
  *) echo "Other error: $?"; exit 1 ;;
esac

Output Formats

Most commands support multiple output formats for different use cases.

Default human-readable format with colors and formatting:

epack inspect evidence.epack 
Pack:        evidence.epack
Stream:      myorg/prod
Created:     2025-02-21T10:30:00Z
Artifacts:   3 files (1.2 MB)
Signed:      ✓ keyless (security@company.com)
Digest:      sha256:a1b2c3d4...

Machine-readable JSON with --json flag:

{
  "pack": "evidence.epack",
  "stream": "myorg/prod",
  "created": "2025-02-21T10:30:00Z",
  "artifacts": 3,
  "size_bytes": 1258291,
  "signed": true,
  "signer": {
    "subject": "security@company.com",
    "issuer": "https://accounts.google.com"
  },
  "digest": "sha256:a1b2c3d4..."
}

Minimal output with -q flag for scripting:

sha256:a1b2c3d4e5f6...
Commands

build

Core

Create an Evidence Pack from artifacts. Bundles files with metadata into a verifiable package.

epack build <output.epack> [files...] --stream <stream> 
# Build from files
epack build evidence.epack ./reports/*.pdf --stream myorg/prod

# Include multiple directories
epack build evidence.epack ./configs ./logs --stream myorg/prod
# Explicit file mapping (src:dest)
epack build evidence.epack --stream myorg/prod \
  --file ./local/report.pdf:artifacts/soc2.pdf \
  --file ./local/config.json:artifacts/config.json

Use src:dest format to control artifact paths inside the pack.

# Read artifact from stdin
curl -s https://api.example.com/data | \
  epack build evidence.epack --stream myorg/prod \
  --stdin artifacts/api-response.json

# Combine stdin with files
cat config.yaml | epack build out.epack ./logs --stream myorg/prod \
  --stdin artifacts/config.yaml
.github/workflows/build-pack.yml 
- name: Build Evidence Pack
  run: |
    epack build evidence.epack ./artifacts --stream ${{ github.repository }} \
      --source "github-collector:1.0.0"
Flags 7
-s, --stream required Stream identifier (e.g., myorg/prod). Uniquely identifies this evidence stream.
-f, --file File mapping (src:dest or src). Can be repeated.
--stdin Read artifact from stdin with given path inside pack.
--content-type Default MIME type for artifacts (auto-detected if omitted).
-o, --output Output path (alternative to positional argument).
--force Overwrite existing output file.
--source Source collector metadata (name:version). Can be repeated.
See also: merge sign Collection Guide

sign

Core Sigstore

Sign a pack with Sigstore. Creates a cryptographic attestation binding your identity to the pack contents.

epack sign <pack.epack> [flags] 
# Keyless signing (opens browser for OIDC auth)
epack sign evidence.epack

# Preview what would be signed
epack sign evidence.epack --dry-run

Opens your browser to authenticate with Google, GitHub, or Microsoft. No keys to manage!

GitHub Actions 
permissions:
  id-token: write

- name: Sign Evidence Pack
  run: epack sign evidence.epack -y  # Skip confirmation
GitHub Actions: Grant id-token: write. epack automatically mints the Sigstore OIDC token from the ambient GitHub Actions endpoint. 
# Sign with private key (PEM format)
epack sign evidence.epack --key ./private.pem

# Skip transparency log (private signing)
epack sign evidence.epack --key ./private.pem --no-tlog
Note: Key-based signing requires you to manage and secure your private keys. Keyless signing is recommended for most use cases.
Flags 7
--oidc-token OIDC token for keyless signing. Also reads from EPACK_OIDC_TOKEN. GitHub Actions uses ambient OIDC automatically when available.
--key Path to private key (PEM format) for key-based signing.
-y, --yes Skip confirmation prompt.
--dry-run safe Show what would be signed without signing.
--no-tlog Skip transparency log (Rekor). Reduces verifiability
--tsa Timestamp authority URL(s) for timestamping.
--insecure-allow-custom-endpoints Use with caution Allow custom Sigstore endpoints (TSA, Fulcio, Rekor).
See also: verify Security Model CI/CD Guide

verify

Core

Verify pack integrity and signatures. Confirms the pack hasn't been tampered with and validates signer identity.

epack verify <pack.epack> [flags] 
# Basic verification (requires identity flags in production)
epack verify evidence.epack

# Integrity only (no signature required)
epack verify --integrity-only evidence.epack
# Require specific signer identity
epack verify evidence.epack \
  --issuer "https://accounts.google.com" \
  --subject "security@vendor.com"

# Pattern matching for organizations
epack verify evidence.epack \
  --issuer "https://accounts.google.com" \
  --subject-regexp ".*@vendor\\.com$"
Security: Always verify signer identity in production. Without --issuer and --subject, you're only checking that someone signed it.
GitHub Actions 
# Verify packs came from trusted CI/CD
epack verify evidence.epack \
  --issuer "https://token.actions.githubusercontent.com" \
  --subject-regexp "https://github.com/myorg/.*"
# Offline verification (skip transparency log check)
epack verify --offline evidence.epack \
  --issuer "https://accounts.google.com" \
  --subject "security@vendor.com"

# With custom trust root
epack verify evidence.epack --trust-root ./sigstore-root.json
Flags 10
--issuer Required OIDC issuer (exact match). The identity provider that authenticated the signer.
--issuer-regexp Required OIDC issuer (regexp pattern).
--subject Required certificate subject (exact match). The email or identity of the signer.
--subject-regexp Required certificate subject (regexp pattern).
--offline Use embedded Rekor/TSA timestamps only; requires --trust-root.
--integrity-only Only verify digests, skip attestation verification.
--require-attestation Fail if no attestations present (default for production).
--insecure-skip-identity-check INSECURE Accept any valid signer. Only use for testing.
--insecure-skip-embedded-verify INSECURE Skip verification of embedded attestations.
--trust-root Path to custom Sigstore trust root JSON.
See also: sign inspect Trust Levels

inspect

Core

Display pack metadata. Shows stream, artifacts, signatures, and other details.

epack inspect <pack.epack> [flags] 
epack inspect evidence.epack
epack inspect --digest evidence.epack      # Just the pack digest
epack inspect --json evidence.epack        # JSON format
epack inspect --raw evidence.epack         # Raw manifest.json
epack inspect --summary evidence.epack     # Condensed output
Flags 3
--digest Show only pack_digest (useful for scripting).
--raw Output raw manifest.json without formatting.
--summary Condensed single-line summary output.
See also: list verify

list

Core

List pack contents. Shows artifacts, attestations, or source collectors.

epack list [pack.epack]
epack list <subcommand> <pack.epack> [flags]

Subcommands

artifacts

List artifacts in the pack

attestations

List attestations (signatures)

sources

List source collectors

epack list artifacts evidence.epack
epack list artifacts -l evidence.epack          # Detailed view
epack list artifacts --filter "*.json" evidence.epack
epack list attestations evidence.epack
epack list sources evidence.epack
Flags 2
-l, --long Detailed information including size and digest.
--filter Filter by path pattern (glob syntax).
See also: inspect extract

extract

Core

Extract artifacts from a pack. Writes files to disk while preserving directory structure.

epack extract <pack.epack> [path...] [flags] 
# Extract specific artifact
epack extract evidence.epack artifacts/config.json

# Extract all artifacts
epack extract --all evidence.epack

# Extract to specific directory
epack extract --all -o ./extracted evidence.epack

# Filter and preview
epack extract --all --filter "*.json" --dry-run evidence.epack
Flags 5
-o, --output Output directory (default: current directory).
--all Extract all artifacts.
--filter Filter by path pattern (glob syntax).
--force Overwrite existing files.
--dry-run safe Show what would be extracted without writing files.
See also: list

diff

Core

Compare two packs. Shows added, removed, and changed artifacts between versions.

epack diff <old.epack> <new.epack> [flags] 
epack diff last-year.epack this-year.epack
epack diff --artifact artifacts/config.json old.epack new.epack
epack diff --json old.epack new.epack
epack diff -C 5 old.epack new.epack   # 5 lines context
Flags 2
-a, --artifact Compare specific artifact by path.
-C, --context Lines of context for text diffs (default: 3).
See also: inspect merge

merge

Core

Combine multiple packs into one. Useful for aggregating vendor evidence or combining collector outputs.

epack merge <output.epack> <pack1.epack> <pack2.epack> ... --stream <stream> 
# Basic merge
epack merge combined.epack vendor-a.epack vendor-b.epack \
  --stream myorg/all-vendors

# Glob patterns
epack merge combined.epack vendor-*.epack --stream myorg/all-vendors

# Preview merge
epack merge combined.epack vendor-*.epack --stream myorg/all-vendors --dry-run
# Verify source packs during merge
epack merge combined.epack vendor-*.epack \
  --stream myorg/all-vendors \
  --include-attestations \
  --issuer "https://accounts.google.com" \
  --subject-regex ".*@trusted-vendor\\.com$" \
  --merged-by "security-team"

Using --include-attestations embeds the original signatures, creating an audit trail.

Flags 11
-s, --stream required Stream identifier for merged pack.
--merged-by Identifier of who performed the merge.
--include-attestations Embed source pack attestations in merged pack.
--force Overwrite existing output file.
--dry-run safe Show what would be merged without creating output.
--issuer Required OIDC issuer for source attestations.
--subject Required exact subject identity.
--subject-regex Required subject pattern (regex).
--insecure-skip-identity-check INSECURE Accept source attestations from any signer.
--insecure-skip-attestation-verify INSECURE Skip attestation verification on source packs.
--trust-root Path to Sigstore trust root JSON.
See also: build verify

version

Core

Show version information including build details.

epack version [flags] 
epack version
epack version --json
epack version -v    # Verbose: commit, date, Go version
Full Edition Commands below require -tags components build

new

Full Edition

Create a new epack project. Scaffolds a complete project structure with config, sample pack, and git setup.

epack new <directory> [flags] 
epack new my-pipeline
epack new .                          # Initialize current directory
epack new my-pipeline --force       # Allow non-empty directory
epack new my-pipeline --skip-sample --skip-git

Created Files

  • epack.yaml - Project configuration
  • packs/ - Output directory for packs
  • sample.epack - Example pack
  • README.md - Project documentation
  • .gitignore - Ignores runtime .epack/ state while keeping .epack/hooks/ tracked

This keeps caches and downloaded runtime state out of git while reserving .epack/hooks/ for committed project-level customization.

Flags 3
--force Allow non-empty directory.
--skip-sample Don't create sample pack.
--skip-git Don't create .gitignore.

new vs init

new init
Creates directory ✓ ✗
Works in existing project ✗ ✓
Creates sample pack ✓ (optional) ✓ (optional)
See also: init install

init

Full Edition

Initialize epack in existing directory. Adds configuration without creating a new project and updates the managed .gitignore block to keep .epack/hooks/ tracked.

epack init [flags] 
epack init
epack init --skip-sample
Flags 2
--skip-sample Don't create sample pack.
-f, --force Overwrite existing epack.yaml.
See also: new

collect

Full Edition Recommended

One-command workflow: lock → sync → run → build. This is the primary command for generating evidence packs.

epack collect [flags] 
epack collect
epack collect --frozen              # CI mode: strict verification
epack collect -c epack.yaml        # Specific config file
epack collect -o output.epack       # Custom output file
epack collect --timeout 2m         # Collector timeout
Tip: Use --frozen in CI/CD to fail on any dependency mismatch. This ensures reproducible builds.
Flags 6
-c, --config Path to epack config file (default: epack.yaml).
--frozen Fail on any mismatch (CI mode). Requires lockfile to be up-to-date.
-o, --output Output pack file path.
--timeout Timeout per collector execution (default: 10m).
--progress Progress display mode: auto|tty|plain|json|quiet.
--parallel Max parallel collector executions (0=auto).
See also: install collector run Collection Guide

install

Full Edition

Lock if needed and download binaries. Combines lock and sync in one command.

epack install [flags] 
epack install
epack install --all-platforms      # Lock and sync all platforms
Flags 4
-c, --config Path to epack config file (default: epack.yaml).
--frozen Fail on any mismatch (CI mode).
--all-platforms Lock and sync all available platforms.
--platform Platforms to lock (comma-separated).
See also: lock sync

lock

Full Edition

Resolve dependencies and write lockfile. Creates epack.lock with pinned versions and checksums.

epack lock [flags] 
epack lock
epack lock --all-platforms
epack lock --platform linux/amd64,darwin/arm64
Flags 3
-c, --config Path to epack config file.
--all-platforms Lock all available platforms.
--platform Platforms to lock (comma-separated).
See also: sync update

sync

Full Edition

Download binaries from lockfile. Fetches and verifies collectors/tools specified in epack.lock.

epack sync [flags] 
epack sync
epack sync --frozen  # CI mode: fail on mismatch
Flags 3
-c, --config Path to epack config file.
--frozen CI mode: fail on any mismatch.
--insecure-skip-verify Skip signature verification (not recommended).
See also: lock install

update

Full Edition

Update collector/tool versions and re-lock. Checks for newer versions and updates the lockfile.

epack update [flags] 
epack update                # Update all collectors
epack update github aws     # Update specific collectors
Flags 1
-c, --config Path to epack config file.
See also: lock

collector

Full Edition

Collector management commands. Run collectors directly without the full collect workflow.

epack collector <subcommand> [flags]

Subcommands

run

Run collectors and build pack

epack collector run
epack collector run -o output.epack
epack collector run --timeout 5m

For managed credential development flows, set EPACK_INSECURE_CREDENTIAL_BROKER_URL to use a custom broker.

See also: collect

tool

Full Edition

Tool discovery and execution. Run analysis tools on evidence packs.

epack tool <subcommand> [flags]

Subcommands

<name>

Execute a configured tool

list

List available tools

info <name>

Show tool details

source <name>

Show tool provenance

catalog search

Search tool catalog

catalog refresh

Update tool catalog

verify <name>

Verify tool binary

# Execute configured tools
epack tool ask --pack vendor.epack "What MFA policies exist?"
epack tool policy --pack vendor.epack

# Discovery
epack tool list
epack tool info ask
epack tool catalog search "policy"
See also: Building Tools

utility

Full Edition

Manage and run globally installed epack utilities. Unlike project-specific collectors and tools, utilities are installed globally for the current user in ~/.epack/.

epack utility <name> [args]
epack utility <subcommand> [flags]

Subcommands

<name> [args]

Run an installed utility

install <name>[@version]

Install a utility from the catalog

list

List installed utilities

remove <name>

Remove an installed utility

# Install a utility from the catalog
epack utility install viewer

# Install a specific version
epack utility install viewer@v0.1.31

# Run an installed utility
epack utility viewer pack.epack
epack utility exporter evidence.epack --format xlsx

# List installed utilities
epack utility list

# Remove a utility
epack utility remove viewer
Install Flags 4
--refresh Refresh the catalog before lookup.
--dry-run Show what would be installed without making changes.
--insecure-skip-verify Skip Sigstore signature verification (NOT RECOMMENDED).
--insecure-trust-on-first Trust digest without Sigstore verification (NOT RECOMMENDED).
Root Flags 1
--insecure-allow-unpinned Skip digest verification for installed utilities (NOT RECOMMENDED).
Security: Utility binaries are verified against their lockfile digest before execution (TOCTOU-safe). The binary is copied while hashing to ensure you execute exactly the bytes you verified.
Utilities vs Tools: Utilities are globally installed helper applications (stored in ~/.epack/). Tools are project-specific plugins configured in epack.yaml and run via epack tool.
See also: tool Building Tools Guide

catalog

Full Edition

Search and manage the unified component catalog. Searches across collectors, tools, remotes, and utilities.

epack catalog <subcommand> [flags]
search [query]

Search the catalog for components

refresh

Update the local catalog cache

# Search for components matching "github"
epack catalog search "github"

# Search for tools only
epack catalog search "policy" --kind tool

# Search for collectors
epack catalog search --kind collector

# List all available remotes
epack catalog search --kind remote

# Refresh the catalog cache
epack catalog refresh
search Flags 2
--kind Filter by component type: collector, tool, remote, or utility.
--refresh Refresh the catalog before searching.
Note: The epack tool catalog command is deprecated. Use epack catalog instead for a unified view of all component types.
See also: collector tool utility

pull

Full Edition

Pull an evidence pack from a remote registry. Downloads and optionally verifies the pack.

epack pull <remote> [ref] [flags] 
# Pull latest pack
epack pull locktivity

# Pull to specific output path
epack pull locktivity -o ./packs/evidence.epack

# Preview what would be pulled (dry-run)
epack pull locktivity --dry-run
# Pull specific version
epack pull locktivity --version v1.2.3

# Pull by release ID
epack pull locktivity --release rel_abc123

# Using positional ref argument
epack pull locktivity v1.2.3
# Pull by digest (immutable, for reproducibility)
epack pull locktivity --digest sha256:abc123...

# Overwrite existing file
epack pull locktivity --force

# Skip verification (not recommended)
epack pull locktivity --verify=false
# Pull from staging environment
epack pull locktivity --env staging

# Override workspace target
epack pull locktivity --workspace acme-prod

# Pull in background (returns immediately)
epack pull locktivity --detach
Flags 11
-o, --output Output path (default: ./.epack).
--version Pull specific version.
--release Pull specific release by ID.
--digest Pull specific pack by digest (immutable).
--env Environment to use (applies config from environments.<env>).
--workspace Override target workspace.
--force Overwrite existing file.
--verify Verify pack integrity after download (default: true).
--dry-run Show what would be pulled without downloading.
-d, --detach Run in background and return immediately.
--insecure-allow-unpinned Allow using adapters not pinned in lockfile (NOT RECOMMENDED).
Exit codes: 0 = Pack pulled successfully, 1 = Pull failed (auth/network error), 2 = Pack verification failed
See also: push verify Remotes Concept

push

Full Edition

Push a pack to a remote registry. Uploads the pack, creates a release, and syncs run records.

epack push <remote> <pack.epack> [flags] 
# Push to Locktivity remote
epack push locktivity packs/evidence.epack

# Non-interactive mode (skip prompts)
epack push locktivity packs/evidence.epack -y
# Push with release labels
epack push locktivity packs/evidence.epack \
  --label monthly \
  --label soc2

# Push with release notes
epack push locktivity packs/evidence.epack \
  --notes "February 2025 compliance release"
# Push to staging environment (uses staging config overrides)
epack push locktivity packs/evidence.epack --env staging

# Override workspace target
epack push locktivity packs/evidence.epack --workspace acme-prod

Environment configs are defined in epack.yaml under environments:

GitHub Actions 
- name: Push to Locktivity
  run: |
    epack push locktivity packs/evidence.epack \
      -y \
      --label automated \
      --notes "Build ${{ github.run_number }}"
Flags 10
--env Environment to use (applies config from environments.<env>).
--workspace Override target workspace.
--label Release label (can be repeated).
--notes Release notes.
--runs-path Additional path to search for run results (can be repeated).
--no-runs Skip run syncing after push.
-y, --yes Non-interactive mode (skip prompts).
--dry-run Show what would be pushed without uploading.
-d, --detach Run in background and return immediately.
--insecure-allow-unpinned Allow using adapters not pinned in lockfile (NOT RECOMMENDED).
Exit codes: 0 = Pack pushed successfully, 1 = Push failed (auth/network error), 2 = Pack malformed
See also: collect sign Remotes Concept Remotes Config

completion

Core

Generate shell completion scripts. Enables tab completion for commands, flags, and arguments.

epack completion <shell> 
# Add to ~/.bashrc
source <(epack completion bash)

# Or install system-wide
epack completion bash > /etc/bash_completion.d/epack
# Add to ~/.zshrc
source <(epack completion zsh)

# Or install to fpath
epack completion zsh > "${fpath[1]}/_epack"
epack completion fish > ~/.config/fish/completions/epack.fish
# Add to your PowerShell profile
epack completion powershell | Out-String | Invoke-Expression