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.
Project Setup
Initialize a new epack project with collectors and tools.
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 |
EPACK_ERROR_FILE |
Path of a file every failed command appends machine-readable code=, exit=, and summary= lines to. Lets CI read stable error codes without scraping logs. See machine-readable errors. |
All commands |
EPACK_HEAD_SHA |
Branch head commit reported as head_sha in runner context. Set it on pull_request workflows, where GITHUB_SHA is the ephemeral merge commit rather than the head. |
remote report-lock, push |
Configuration Precedence
- Command-line flags (highest priority)
- Environment variables
- Project config (
epack.yaml) - 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. |
#!/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:
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...
build
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
- 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. |
sign
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!
permissions: id-token: write - name: Sign Evidence Pack run: epack sign evidence.epack -y # Skip confirmation
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
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). |
verify
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$"
--issuer and
--subject, you're only checking that someone signed it.
# 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. |
inspect
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. |
list
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). |
extract
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. |
diff
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). |
merge
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. |
version
Show version information including build details.
epack version [flags]
epack version epack version --json epack version -v # Verbose: commit, date, Go version
-tags components build
new
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 configurationpacks/- Output directory for packssample.epack- Example packREADME.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) |
init
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-sampleFlags 2
--skip-sample |
Don't create sample pack. |
-f, --force |
Overwrite existing epack.yaml. |
collect
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
--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). |
install
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). |
lock
Resolve dependencies and write lockfile. Creates epack.lock with pinned versions, checksums, and per-component verification status.
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). |
sync
Download binaries from lockfile. Fetches and verifies collectors/tools specified in epack.lock. Use --locked on clean CI machines to install exactly the locked versions and fail on any drift; use --frozen to verify an existing install without downloading anything.
epack sync [flags]
epack sync epack sync --locked # CI install: exact locked versions, fail on drift epack sync --frozen # CI verify: no downloads, fail on mismatch
Flags 4
-c, --config |
Path to epack config file. |
--locked |
Clean-machine CI install: install exactly the locked versions with full signature and digest verification, fail on any drift (modified binaries, unpinned externals, a pin outside its configured range), and never rewrite the lockfile. Mutually exclusive with --frozen. |
--frozen |
Verify-only CI mode: fail on any mismatch or missing platform. Never downloads, so it always fails on a fresh machine; use --locked there instead. |
--insecure-skip-verify |
Skip signature verification (not recommended; rejected together with --locked or --frozen). |
update
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. |
collector
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.
tool
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"
utility
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@v1.2.3 # 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). |
~/.epack/). Tools are project-specific plugins configured in epack.yaml and run via epack tool.
catalog
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. |
epack tool catalog command is deprecated. Use epack catalog instead for a unified view of all component types.
pull
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: ./ |
--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). |
0 = Pack pulled successfully,
1 = Pull failed (auth/network error),
2 = Pack verification failed
push
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:
- 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). |
0 = Pack pushed successfully,
1 = Push failed (auth/network error),
2 = Pack malformed
remote report-lock
Report the current epack.lock.yaml to a remote without pushing a pack. Sends the raw lockfile, its SHA-256, a normalized component summary, and runner context. Built for CI bootstrap and refresh flows where the platform needs the resolved lock before any evidence exists. Requires an adapter that advertises the lock_report capability.
epack remote report-lock <remote> [flags]
# Report a freshly resolved lock during setup bootstrap epack remote report-lock locktivity --reason bootstrap # Report a refreshed lock from a config-change branch epack remote report-lock locktivity --reason refresh # Report a frozen-run failure with a stable error code epack remote report-lock locktivity --reason frozen_check \ --outcome failure --failure-code lock_config_mismatch
Flags 7
--reason |
Why the report exists: bootstrap, refresh, or frozen_check (default). |
--outcome |
success (default) or failure. Failure reports omit the raw lockfile. |
--failure-code |
Stable error code for failed reports (required with --outcome failure). Read it from EPACK_ERROR_FILE rather than scraping logs. |
--failure-message |
Human-readable summary for failed reports. |
--env |
Environment to use (applies config from environments.<env>). |
--workspace |
Override target workspace. |
--insecure-allow-unpinned |
Allow adapters not pinned in the lockfile (not recommended). |
completion
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