CLI Reference

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

# 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

# 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"

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

# Keyless signing (opens browser for OIDC auth)
epack sign evidence.epack

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

permissions:
  id-token: write

- name: Sign Evidence Pack
  run: epack sign evidence.epack -y  # Skip confirmation

# 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

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

# 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$"

# 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

# A pack signed with a key carries no certificate; check it against the signer's public key
epack verify evidence.epack --public-key signer.pem

# Accept any of several keys; the one that verifies names the signer
epack verify evidence.epack --public-key runner-a.pem --public-key runner-b.pem

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

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

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

Subcommands

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

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

# 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

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

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

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

# 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"

Show version information including build details.

At a terminal, the full build also checks at most once a day for a newer release while a command runs, and when one is out, says so after the command finishes with how to upgrade. It asks GitHub without credentials and gives up after two seconds. There is no check in CI mode or with --quiet, and EPACK_NO_UPDATE_NOTIFIER turns it off.

epack version
epack version --json
epack version -v    # Verbose: commit, date, Go version

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

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

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

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
epack init --skip-sample

One-command workflow: lock → sync → run → build. This is the primary command for generating evidence packs. When collectors fail, no pack is built, and each failed collector is reported with a code such as auth_failed; see collector run failures.

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

Run the workflow a project describes, start to finish: install the locked collectors, tools, and remote adapters, run the pre-collect hook, collect, run the post-collect hook, run each tool on the pack, sign, and push. With a configuration name, the configuration is fetched from the remote you last signed in to (or --remote) into a folder named after it, refreshed when the folder exists, and the run happens there. Without a name, the run uses the project in the current directory. From inside a folder a clone created, a run by that name refreshes the folder in place. When a stage fails, the failure is reported to the remote with a stable code, and a collect failure names the collector. A remote whose adapter takes progress is told as each stage, collector, and tool starts, finishes, or fails.

# Fetch a configuration from the remote you signed in to and run it
epack run northwind-production

# Run the project in the current directory
epack run

# Check sign-in, the lock, variables, credentials, and publishers; collect nothing
epack run --check

# In CI: no prompts, sign with a key
epack run --yes --key "$EPACK_SIGNING_KEY"

In a folder fetched from a remote, --check locks the configuration as the first run would. In your own project, it reports a missing or stale lock instead. With a current lock, it installs the locked collectors, tools, and remote adapter as a run does before it signs in. In a terminal, it also offers to register this machine's key for the configuration when the remote does not hold it, as a run does. Variables are reported as N of M ready, one line each with where the value comes from: the environment, your keychain, stored but awaiting approval, or not set. A variable that is not ready comes with the epack secret command that resolves it. Variables the configuration lists as optional are reported with the rest but not counted.

The variables a configuration lists under secrets come from the environment first and from your keychain second, for the folder's configuration on its remote. A stored value is used only once it is approved for the components that read it as they are now; a revision that changes a reader stops the run before collecting until epack secret approve. Runs and checks never prompt, and a CI job never reads the keychain.

A run from a terminal signs in your browser, as you. Its collectors get their managed credentials through that sign-in when the remote's adapter supports it. A machine with a key from epack key create signs with it once the remote approves the key. A configuration fetched from a remote may only run collectors, tools, and remote adapters from publishers you trust: in a terminal, epack asks once for each new publisher, and a job names them with --trust-publisher or EPACK_TRUSTED_PUBLISHERS.

A run by name checks the revision it fetched before installing anything: the variables and keychain secrets it reads, approval for stored secrets, trust in its publishers, and the epack release the remote says it needs. When something is missing, the run lists it with where to add it and asks the remote for the newest earlier revision that runs without it. That revision runs from .epack/fallback inside the folder, and the fetched revision stays in the folder for you to finish. With no earlier revision that runs here, the run stops, reports what is missing to the remote, and exits. A job with no folder signs in for the configuration with EPACK_PIPELINE_ID and the job's GitLab ID token or the runner's key, through the adapter installed for the user, which must come from a publisher the job trusts.

Keep the variables a configuration lists under secrets in your operating system keychain, scoped to this configuration on its remote, so a run finds them in any terminal. The environment always wins: a variable set in the shell reaches the components that list it as before, and the keychain is read only for the rest. A stored value is approved for the components that read it as they are now. When a later revision changes one of them, or adds one, the secret needs approval again before a run uses it. Run these commands in the folder epack remote clone created. Runs and checks never prompt; only these commands do.

Subcommands

# Walk every missing and unapproved secret; each value is read hidden
epack secret setup

# Paste one value, hidden
epack secret set AZURE_CLIENT_SECRET

# Store a key or a JSON credential from a file
epack secret set OKTA_PRIVATE_KEY --from-file ~/Downloads/okta.pem

# Pipe a value in from a password manager
op read op://Vault/item/field | epack secret set SENTRY_AUTH_TOKEN --stdin

# Review what changed and approve
epack secret approve

# Names, readers, and approval state; never values
epack secret list

epack secret remove AZURE_CLIENT_SECRET

# Clean up after a pipeline is gone
epack secret list --all
epack secret remove AZURE_CLIENT_SECRET --scope locktivity:cfg_abc123

setup is the one command meant to be interactive: each secret the keychain lacks is asked for, hidden, and stored, and each one that needs approval again is shown with what changed and approved on a yes. Enter skips a value. It ends with what was skipped or left unapproved and the next step, epack run --check. set refuses a value given as an argument, since it would land in shell history; in a terminal the value is read hidden, --stdin reads a pipe to the end, and --from-file reads a file. Exactly one trailing newline is stripped. approve prints each change to a reader since the approval and what it means before asking; without a name it walks every secret that needs approval. list never shows a value.

The keychain is /usr/bin/security on macOS, the Secret Service over D-Bus on Linux, and Credential Manager on Windows. A value too large for one item is split across items that a header item describes, so an interrupted write keeps the old value. What epack records about stored secrets, names, readers, approvals, and times but never values, lives in ~/.epack/secrets.yaml, readable only by you. The keychain protects a value at rest and from other user accounts, not from code running as you; see Stored secrets.

Signing keys for runs from this machine. A run from a terminal signs its pack in your browser, as you. A key signs it with nobody at the keyboard, which a scheduled run needs, and keeps your email out of the signature. epack key create keeps the private half in ~/.epack/keys/<remote>.pem, readable only by you, and registers the public half with the remote. Once the remote accepts it, runs from this machine sign with it. Requires an adapter that manages keys.

Subcommands

# Make a key for this machine and register it
epack key create

# Register a key for a configuration by name
epack key create locktivity --for northwind-production

# Write a key for a runner you manage instead of this machine
epack key create --for northwind-production --out ./epack-signing-key.pem

# Show the keys a configuration accepts
epack key list --for northwind-production

# Replace this machine's key; the old one is retired once the new one is accepted
epack key rotate

The remote may hold a new key until someone approves it. The command then shows a code, opens the approval page in your browser, and waits for the code to be entered there. Running the command again registers the same key, so it is safe to repeat. rotate registers the new key first and retires the old one only once the new one is accepted, so a failed rotation leaves the old key working. A retired key signs nothing new, and packs it already signed stay trusted.

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

epack install
epack install --all-platforms      # Lock and sync all platforms

Resolve dependencies and write lockfile. Creates epack.lock with pinned versions, checksums, and per-component verification status. Each component resolves to the newest release its version range allows, and entries for components and files the config no longer lists are removed. With --keep-pins, a pinned version stays while its range allows it, and only components that are new, out of range, or from another source are resolved.

epack lock
epack lock --all-platforms
epack lock --platform linux/amd64,darwin/arm64
epack lock --keep-pins       # Resolve only new or out-of-range components

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
epack sync --locked  # CI install: exact locked versions, fail on drift
epack sync --frozen  # CI verify: no downloads, fail on mismatch

Update collector/tool versions and re-lock. Checks for newer versions and updates the lockfile. When a component moves to a new version, every platform already in the lockfile is re-locked against the new release.

epack update                # Update all collectors
epack update github aws     # Update specific collectors

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

Subcommands

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 discovery and execution. Run analysis tools on evidence packs.

Subcommands

# 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"

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

Subcommands

# 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

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

# 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

Sign in to a remote with your browser. epack opens the remote's sign-in page, and once you allow epack there, the browser returns to epack at 127.0.0.1 on this machine and the adapter finishes the sign-in. The adapter keeps the session, so later commands need no token. The remote you sign in to becomes the default for configuration names in run and remote clone, and its adapter's publisher is trusted for configurations fetched from it. Outside a project, the adapter is installed for your user from the catalog and verified before it runs; inside a project that names the remote, the project's pinned adapter is used.

epack remote login locktivity

# Over SSH: forward a fixed port when you connect, then open the printed link on your own computer
ssh -L 8400:127.0.0.1:8400 host
epack remote login locktivity --port 8400 --no-browser

Fetch a named configuration from a remote and write it into a folder: epack.yaml, the hooks, any profile files, and the lock when the remote has one. The remote is the one you last signed in to, or --remote. The folder defaults to the configuration's name, or to the current folder when it is the one an earlier clone of that configuration created, even if the configuration was renamed since. Run it again to pick up a newer revision. Inside a folder a clone created, the name can be left out: the folder is refreshed from the configuration and remote it was cloned from. Files you have edited are left alone unless you pass --force, and hook scripts are never overwritten. When the revision carries a lock, it replaces a lock that a run wrote in the folder. A folder cloned from another configuration is refused unless you pass --force. After a fetch that changed something, epack prints what the configuration will run and read, counting a variable as set when the environment or your keychain holds it.

epack remote clone northwind-production
epack remote clone northwind-production ./compliance
epack remote clone northwind-production --remote locktivity

# Inside a folder a clone created, pick up a newer revision
epack remote clone

# Replace files you have edited with the remote's
epack remote clone northwind-production --force

Update the adapter installed for you to the newest release the catalog lists. The adapter you signed in with is pinned in ~/.epack/remotes.lock and never moves on its own. This command moves it to the newest release of the same repository, verified the same way as the first install. The new release is installed and started before the pin moves, so a release that fails leaves the old one in place. A project that names the remote pins its own adapter in epack.lock.yaml; this command does not change that pin.

epack remote update
epack remote update locktivity

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

# 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

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

# 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

- name: Push to Locktivity
  run: |
    epack push locktivity packs/evidence.epack \
      -y \
      --label automated \
      --notes "Build ${{ github.run_number }}"

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. A failure report also lists the collectors that failed, with each one's failure code and exit code, when the last error in EPACK_ERROR_FILE has the code given as --failure-code.

# 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

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

# 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