CLI workflows

Use this page when you know the four commands already and want repeatable ways to combine them.

Workflow: create the first useful artifact

npx filepacks pack ./run-output --output ./run-output.fpk
npx filepacks inspect ./run-output.fpk

Use this when you want fast confirmation that:

the output directory is packageable
the artifact was created successfully
the resulting file count and byte count look reasonable

Workflow: trust but verify

If an artifact is going to be uploaded, shared, or used as a baseline, verify it first:

npx filepacks verify ./run-output.fpk

Use this before:

attaching the artifact to a ticket or pull request
comparing against another artifact
storing the artifact as an accepted baseline

Workflow: baseline vs candidate review

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

This is the core review loop for repeated runs:

0 means no packaged files changed
20 means one or more packaged files changed
1 means command or artifact failure

Workflow: received artifact from someone else

When someone hands you a .fpk file:

npx filepacks inspect ./received.fpk
npx filepacks verify ./received.fpk

inspect tells you what it claims to be. verify tells you whether the payload still matches the manifest.

Workflow: accept a new baseline

The public OSS CLI does not manage baseline aliases or tags. If the candidate is acceptable, update your baseline explicitly in your own storage or workflow. For example:

cp ./candidate.fpk ./baseline.fpk

Or upload the accepted candidate artifact to the location your CI jobs already use as the baseline source.

Workflow: use from a shell script

set +e
npx filepacks compare ./baseline.fpk ./candidate.fpk
status=$?
set -e

if [ "$status" -eq 0 ]; then
  echo "No structural changes"
elif [ "$status" -eq 20 ]; then
  echo "Changes detected; review candidate artifact"
else
  echo "Comparison failed"
  exit "$status"
fi

Treat 20 as “artifact changed”, not “tool crashed”.

Workflow: 60-second AI-assisted software demo

Use this when you want a short demo that looks like real AI-assisted software work instead of a single summary.txt file. Create two tiny directories with the kinds of files an agent-assisted coding run often produces:

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

printf 'Task: checkout fix\nStatus: success\n' > ./demo/baseline/agent-task-summary.md
printf 'diff --git a/app.js b/app.js\n+console.log("baseline")\n' > ./demo/baseline/changes.patch
printf 'PASS smoke test\n' > ./demo/baseline/test-output.txt
printf '{"source":"agent","step":"baseline"}\n' > ./demo/baseline/metadata.json

printf 'Task: checkout fix\nStatus: success\nReviewed by human\n' > ./demo/candidate/agent-task-summary.md
printf 'diff --git a/app.js b/app.js\n+console.log("candidate")\n' > ./demo/candidate/changes.patch
printf 'PASS smoke test\nPASS checkout test\n' > ./demo/candidate/test-output.txt
printf '{"source":"agent","step":"candidate"}\n' > ./demo/candidate/metadata.json

Then run the full review loop:

npx filepacks pack ./demo/baseline --output ./baseline.fpk
npx filepacks pack ./demo/candidate --output ./candidate.fpk
npx filepacks inspect ./candidate.fpk
npx filepacks verify ./candidate.fpk
npx filepacks compare ./baseline.fpk ./candidate.fpk

That flow shows why filepacks matters for AI-assisted software work: one portable artifact preserves the agent’s files, verify confirms they still match the manifest, and compare shows exactly what changed before a human decides whether to ship.

Workflow: choose the right command

Goal	Command
Create an artifact from a directory	`pack`
Read the artifact summary	`inspect`
Confirm the artifact is intact	`verify`
Check whether packaged files changed	`compare`

Continue to the individual command pages for argument and output details.

Getting started

CLI

Artifacts

Guides

Workflow: create the first useful artifact

Workflow: trust but verify

Workflow: baseline vs candidate review

Workflow: received artifact from someone else

Workflow: accept a new baseline

Workflow: use from a shell script

Workflow: 60-second AI-assisted software demo

Workflow: choose the right command

​Workflow: create the first useful artifact

​Workflow: trust but verify

​Workflow: baseline vs candidate review

​Workflow: received artifact from someone else

​Workflow: accept a new baseline

​Workflow: use from a shell script

​Workflow: 60-second AI-assisted software demo

​Workflow: choose the right command

Workflow: create the first useful artifact

Workflow: trust but verify

Workflow: baseline vs candidate review

Workflow: received artifact from someone else

Workflow: accept a new baseline

Workflow: use from a shell script

Workflow: 60-second AI-assisted software demo

Workflow: choose the right command