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.

The public OSS CLI is useful in CI when you want generated files to become deterministic, portable evidence instead of a loose job workspace.

​
Basic CI pattern

  1. Run a job that generates output files
  2. Package that directory with npx filepacks pack
  3. Verify the artifact with npx filepacks verify
  4. Compare it against a known baseline artifact with npx filepacks compare
  5. Upload the .fpk file as a job artifact for human review if needed
npx filepacks pack ./build-output --output ./candidate.fpk
npx filepacks verify ./candidate.fpk
npx filepacks compare ./baseline.fpk ./candidate.fpk

​
Why this works well in CI

  • the artifact is one file you can upload
  • verify confirms integrity before downstream use
  • compare gives deterministic exit codes for “same”, “changed”, and “failed”
  • reviewers can inspect the exact same artifact later

​
Exit handling

For the current public CLI:
  • verify exits 0 when the artifact is valid
  • verify exits 1 when the artifact is invalid
  • compare exits 0 when the artifacts are identical
  • compare exits 20 when files differ
That makes it easy to separate “artifact changed” from “command failed”.

​
Example: strict GitHub Actions gate

- name: Install filepacks
  run: npm install -g filepacks

- name: Package output
  run: filepacks pack ./build-output --output ./candidate.fpk

- name: Verify artifact
  run: filepacks verify ./candidate.fpk

- name: Compare against baseline
  run: filepacks compare ./baseline.fpk ./candidate.fpk

- name: Upload artifact for review
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: candidate
    path: candidate.fpk
If you want any structural difference to fail the job, this is enough.

​
Example: preserve artifact and fail only after capture

If you want to keep the candidate artifact even when the output changed, capture the exit code explicitly: 
- name: Compare against baseline
  id: compare
  shell: bash
  run: |
    set +e
    npx filepacks compare ./baseline.fpk ./candidate.fpk
    status=$?
    set -e

    if [ "$status" -eq 1 ]; then
      exit 1
    fi

    echo "status=$status" >> "$GITHUB_OUTPUT"

- name: Upload candidate artifact
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: candidate
    path: candidate.fpk

- name: Fail when output changed
  if: steps.compare.outputs.status == '20'
  run: exit 1
This treats 20 as “review needed” instead of “tool failure”.

​
Agent and eval runner workflows

When an AI coding agent or eval runner produces output files, pack the output directory as an artifact immediately after the run: 
# Pack agent output after the run completes
npx filepacks pack ./agent-output --output ./run-$(date +%s).fpk

# Or in an eval harness, pack each run by ID
npx filepacks pack ./eval-output --output ./eval-$RUN_ID.fpk

# Compare the new run against the last accepted run
npx filepacks compare ./eval-baseline.fpk ./eval-$RUN_ID.fpk
compare exits 0 if the output is structurally identical to the baseline and 20 if anything changed. Either exit code is usable in a script or CI job to decide whether to accept the run. Use @filepacks/core directly to build this into an eval harness: 
import {pack, compare} from '@filepacks/core'

const run = await pack({input: outputDir, output: `eval-${runId}.fpk`})
const diff = await compare({baseline: 'eval-baseline.fpk', candidate: `eval-${runId}.fpk`})

if (!diff.ok) {
  console.log(`${diff.summary.changed} file(s) changed`)
  // diff.changed[] has per-file details
}

​
What to preserve

For the current OSS workflow, keep at least:
  • candidate.fpk
  • the baseline artifact used for comparison, if it is not already versioned elsewhere
  • the job log that captured the compare summary

​
Baseline management

The public OSS surface does not define a baseline registry or tag workflow. In CI, store the baseline artifact explicitly and compare against that file path. Common approaches:
  • commit a known-good .fpk to the repository and compare against it on each run
  • upload the accepted run’s .fpk as a named CI artifact and retrieve it in subsequent jobs

​
Good fit for CI

filepacks works well when you want:
  • reproducible build evidence
  • a reviewable snapshot of generated files
  • a stable baseline-versus-candidate comparison primitive
  • one artifact file that humans and automation can both inspect later