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

# Installation

> Install filepacks for command-line use or add @filepacks/core to your own tooling.

## Requirements

* Node.js `>=18`
* npm

## Choose the interface

| Use this when you want to...                                | Install           |
| ----------------------------------------------------------- | ----------------- |
| Pack, inspect, verify, and compare artifacts from the shell | `filepacks` CLI   |
| Call the same operations from a Node.js tool or harness     | `@filepacks/core` |

## Quick trial

Run filepacks without a persistent install:

```bash theme={null}
npx filepacks --help
```

Use `npx filepacks ...` throughout the docs when you want copy-pasteable commands from a clean shell.

## Persistent install

Install the CLI globally when you want `filepacks` on your `PATH`:

```bash theme={null}
npm install -g filepacks
filepacks --help
```

If you install `filepacks` into a project instead, invoke it with `npx filepacks ...`.

Current public commands:

```bash theme={null}
filepacks pack <input> --output <file>
filepacks inspect <file>
filepacks verify <file>
filepacks compare <baseline> <candidate>
```

## Install the core library

Install `@filepacks/core` when you want structured results in code:

```bash theme={null}
npm install @filepacks/core
```

Minimal example:

```ts theme={null}
import {pack, inspect, verify, compare} from '@filepacks/core'

await pack({input: '/tmp/input', output: '/tmp/example.fpk'})
const artifact = await inspect({artifact: '/tmp/example.fpk'})
const verification = await verify({artifact: '/tmp/example.fpk'})
const diff = await compare({
  baseline: '/tmp/baseline.fpk',
  candidate: '/tmp/example.fpk',
})
```

## Verify the CLI install

```bash theme={null}
npx filepacks --help
```

Or, after a global install:

```bash theme={null}
filepacks --help
```

The help output should list `pack`, `inspect`, `verify`, and `compare`.

## Verify the core install

Your runtime should be able to import `@filepacks/core` and call `pack()`, `inspect()`, `verify()`, and `compare()`.

## First useful command after install

After installation, the fastest way to confirm the workflow is:

```bash theme={null}
npx filepacks pack ./some-output-directory --output ./example.fpk
npx filepacks inspect ./example.fpk
```

That tells you the install works and shows you the shape of the artifact you just created.

## Notes

* Artifact file paths used with `pack --output`, `inspect`, `verify`, and `compare` must end in `.fpk`.
* The CLI does not expose registry, tag, baseline, import, show, or unpack commands in the public OSS surface.
* The core API accepts an optional `name` field when packing. The public CLI does not currently expose a `--name` flag.