> ## 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.

# CLI workflows

> Practical command patterns for first-time use, review loops, CI jobs, and repeated artifact comparisons.

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

## Workflow: create the first useful artifact

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.