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.

​
What is a .fpk file?

A .fpk file is a deterministic POSIX tar archive with:
  • manifest.json as the first entry
  • payload files stored under payload/
The manifest records the artifact name, file count, per-file hashes and sizes, and a payload digest. That makes the artifact self-describing and locally verifiable without unpacking.

​
Why would I use filepacks instead of keeping the directory?

Use filepacks when the directory needs a stable, portable review boundary. A .fpk file gives you:
  • one file instead of a loose tree
  • a canonical manifest
  • deterministic archive bytes
  • local verification
  • structural comparison against another run

​
What commands are publicly supported?

The public CLI supports only:
  • filepacks pack <input> --output <file>
  • filepacks inspect <file>
  • filepacks verify <file>
  • filepacks compare <baseline> <candidate>

​
What should I use filepacks for in practice?

filepacks works best for repeated workflows that produce a directory of output files you want to review, compare, or archive:
  • CI builds: capture a build output as a portable artifact, verify it, and compare it against the last known-good build
  • Agent runs: pack agent output after each run, compare to a previous run to detect unexpected changes
  • Eval pipelines: pack each eval run output, compare against a baseline to track regressions
  • Portable evidence: share a single .fpk file instead of a directory; the recipient can inspect and verify it locally

​
Is filepacks only for humans, or can automation use it too?

Both. Humans can read the summary output and review the changed paths. Automation can use:
  • deterministic artifact files
  • verify success or failure
  • compare exit 0 vs 20
  • @filepacks/core structured results

​
Does the public CLI support tags, baselines, or registries?

No. Those flows are outside the current public OSS surface.

​
Can I inspect an artifact without unpacking it?

Yes. filepacks inspect <file> reads artifact metadata directly from the .fpk file.

​
How do I verify corruption or drift?

Run: 
npx filepacks verify ./artifact.fpk
If the artifact is invalid, verify exits non-zero and reports mismatch lines.

​
How do I compare two artifacts?

Run: 
npx filepacks compare ./baseline.fpk ./candidate.fpk
The command exits 0 if they are structurally identical and 20 if files were added, removed, or changed.

​
Does compare tell me whether the change is good?

No. compare is structural only. It tells you that packaged files changed, not whether the change is correct or desirable.

​
Can I use filepacks from code?

Yes. Install @filepacks/core and call:
  • pack()
  • inspect()
  • verify()
  • compare()

​
Can an AI agent or eval runner use filepacks?

Yes. The CLI and core API are simple enough to integrate directly into an agent workflow or eval harness. After a run produces output files, pack the directory: 
npx filepacks pack ./agent-output --output ./run.fpk
npx filepacks compare ./baseline.fpk ./run.fpk
compare exits 0 if nothing changed and 20 if anything did — that exit code is usable in any script or CI job. The @filepacks/core package exposes the same operations programmatically if you need structured results inside a harness.

​
What does verification prove?

verify proves that the artifact payload still matches the manifest. It does not prove that the files are semantically correct, only that the artifact is internally consistent and intact.

​
Does the public repo support typed artifacts?

No. The current v0 OSS manifest validator rejects typed artifact fields such as schema_version and artifact_type.

​
Are directories stored as archive entries?

No. The public .fpk format stores regular file entries only. Directory entries must not be emitted.

​
What Node version do I need?

The CLI and core packages declare node >=18.