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.

This walkthrough takes a directory of generated output, turns it into a .fpk artifact, and shows how to review it. The same pattern works for agent runs, eval snapshots, CI reports, and any other workflow that emits files.

​
Install the CLI

Quick trial from a clean shell: 
npx filepacks --help
If you want the command on your PATH, install it globally: 
npm install -g filepacks
filepacks --help
The commands below use npx filepacks ... so the walkthrough stays copy-pasteable from a clean local state.

​
Create example output directories

mkdir -p ./demo/baseline
mkdir -p ./demo/candidate

printf 'hello from baseline\n' > ./demo/baseline/summary.txt
printf 'hello from candidate\n' > ./demo/candidate/summary.txt
You now have two output directories that differ by one file.

​
Pack each directory

npx filepacks pack ./demo/baseline --output ./baseline.fpk
npx filepacks pack ./demo/candidate --output ./candidate.fpk
pack writes a deterministic .fpk archive and prints a summary like: 
Pack
input=/absolute/path/to/demo/baseline
output=/absolute/path/to/baseline.fpk
name=baseline
digest=sha256:...
files=1
bytes=20
pack creates one portable .fpk file per directory. The archive digest is printed as sha256:<hex>.

​
Inspect what you created

npx filepacks inspect ./baseline.fpk
Example output: 
Inspect
path=/absolute/path/to/baseline.fpk
name=baseline
version=1
digest=sha256:...
files=1
bytes=20
Use inspect when you want a quick summary: artifact name, format version, digest, file count, and total bytes.

​
Verify integrity before trusting it

npx filepacks verify ./baseline.fpk
Example output: 
Verify
path=/absolute/path/to/baseline.fpk
ok=true
files_checked=1
Use verify before sharing an artifact, uploading it, or using it as a baseline. It confirms that the payload still matches the manifest.

​
Compare baseline and candidate

npx filepacks compare ./baseline.fpk ./candidate.fpk
If the artifacts differ, compare exits with status 20 and prints a structural summary: 
Compare
baseline=/absolute/path/to/baseline.fpk
candidate=/absolute/path/to/candidate.fpk
ok=false
added=0
removed=0
changed=1
changed_file=summary.txt
If the artifacts are identical, compare exits 0 with ok=true. In automation, the exit code matters:
  • 0 means the candidate matches the baseline
  • 20 means one or more packaged files changed
  • 1 means the command was used incorrectly or an artifact could not be read

​
What to look at next

When compare reports a change:
  1. Use the changed_file=, added_file=, and removed_file= lines to find the affected paths.
  2. Review the original output directories or the files inside the .fpk artifact in your own tooling.
  3. If the change is acceptable, store the candidate artifact explicitly as the next baseline. The public OSS CLI does not manage baselines for you.

​
What you just used

  • filepacks pack <input> --output <file>
  • filepacks inspect <file>
  • filepacks verify <file>
  • filepacks compare <baseline> <candidate>
Those four commands are the current public CLI surface.

​
Next steps

  1. Read Why filepacks for when the artifact model is useful.
  2. Use CLI workflows for repeatable patterns in scripts, CI, and short AI-assisted-work demos.
  3. Read Use cases for eval, agent, and review scenarios.
  4. Use Artifacts when you need format-level details.