Skip to main content

Documentation Index

Fetch the complete documentation index at: https://filepacks.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

filepacks is artifact infrastructure for workflows that produce files. It takes a directory of generated output and turns it into one deterministic .fpk file with a canonical manifest. That gives you a stable unit you can:
  • pack after a run completes
  • inspect without unpacking to a working directory
  • verify before you trust or share it
  • compare against another run with predictable exit codes
That makes filepacks a good fit for agent runs, eval outputs, CI evidence, regression review, and portable artifact handoff.

​
What you get from a .fpk artifact

  • One reviewable file instead of a loose directory tree
  • A canonical manifest.json that records file paths, sizes, hashes, counts, and totals
  • Deterministic bytes for the same logical input, so the archive digest is meaningful
  • Local verification that the payload still matches the manifest
  • Manifest-driven comparison that reports added, removed, and changed files consistently

​
Default CLI workflow

npx filepacks pack ./run-output --output ./run.fpk
npx filepacks inspect ./run.fpk
npx filepacks verify ./run.fpk
npx filepacks compare ./baseline.fpk ./run.fpk
These docs default to npx filepacks ... so the examples work from a clean shell. If you install globally with npm install -g filepacks, drop the npx prefix. compare exits 0 when the artifacts are structurally identical and 20 when any packaged file changed. That makes it directly usable in scripts, CI jobs, and agent harnesses.

​
CLI or library?

If you want to…Use
Package and review artifacts from the shellfilepacks CLI
Build artifact handling into a runner, harness, or tool@filepacks/core
Understand the artifact contract itselfspec/FILEPACK_SPEC.md and the artifact reference pages
Use @filepacks/core when you want structured results in code: 
import {pack, inspect, verify, compare} from '@filepacks/core'

await pack({input: '/tmp/run', output: '/tmp/run.fpk'})
const artifact = await inspect({artifact: '/tmp/run.fpk'})
const result = await verify({artifact: '/tmp/run.fpk'})
const diff = await compare({
  baseline: '/tmp/baseline.fpk',
  candidate: '/tmp/run.fpk',
})

​
Public OSS surface

The public OSS surface is intentionally narrow:
  • pack — create a deterministic .fpk artifact from a directory
  • inspect — read artifact metadata from a .fpk file
  • verify — validate the payload against the manifest
  • compare — structurally compare two artifacts
It does not include registries, remote storage, tags, local baseline resolution, typed eval artifacts, hosted dashboards, or cloud workflows.

​
Why teams use it

filepacks is useful when you need output to be:
  • portable enough to hand to another person or another agent
  • inspectable without recreating the original run environment
  • verifiable before you review or compare it
  • comparable across repeated runs, prompts, models, or commits

​
Start here

  1. Start with Quickstart.
  2. Read Why filepacks for the problem framing and boundaries.
  3. Use CLI workflows for practical command patterns.
  4. Read Programmatic API when you want @filepacks/core from Node.js automation.
  5. Read Use cases and Agent workflows for real review loops.
  6. Use Artifacts when you need format and manifest details.