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 it does

compare reads two artifacts and reports whether any packaged file was added, removed, or changed. It is the command to use when you care about repeated-run drift, baseline-versus-candidate review, or CI gating on structural equivalence.

​
Usage

filepacks compare <baseline> <candidate>

​
When to use it

  • comparing a new agent run to the previously accepted run
  • checking whether eval output changed between two runs
  • reviewing generated files in CI
  • deciding whether a candidate artifact needs human attention

​
What compare does

compare performs structural comparison only. It reads both manifests and reports:
  • files added in the candidate
  • files removed from the baseline
  • files changed at the same path
A file is changed when its size or hash differs.

​
Minimal example

npx filepacks compare ./baseline.fpk ./candidate.fpk

​
Expected output shape

Example: 
Compare
baseline=/absolute/path/to/baseline.fpk
candidate=/absolute/path/to/candidate.fpk
ok=false
added=1
removed=0
changed=1
added_file=reports/new.txt
changed_file=summary.txt

​
Exit behavior

  • exit 0: no differences
  • exit 20: one or more differences were found
  • exit 1: usage or file/path error
Treat 20 as “changed”, not “tool failure”.

​
Common mistakes

  • assuming compare explains why a change is good or bad
  • passing a directory instead of a .fpk file
  • relying on implicit baseline lookup; you must provide explicit artifact paths
  • verify before comparing artifacts you plan to trust
  • inspect when you want a quick summary before comparison
  • Diffing for review guidance after the command runs

​
Core API

const result = await compare({
  baseline: '/tmp/baseline.fpk',
  candidate: '/tmp/candidate.fpk',
})

result.mode // 'structural'
result.ok
result.summary
result.added
result.removed
result.changed

​
Scope

The current public OSS command does not define semantic comparison modes, typed artifact decisions, or registry-backed references.