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

# Compare

> Structurally compare two .fpk artifacts by manifest path, size, and hash.

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

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

```bash theme={null}
npx filepacks compare ./baseline.fpk ./candidate.fpk
```

## Expected output shape

Example:

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

## Related commands

* `verify` before comparing artifacts you plan to trust
* `inspect` when you want a quick summary before comparison
* [Diffing](/diffing) for review guidance after the command runs

## Core API

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