Usage

Filepack supports a number of subcommands, including filepack create to create a package, filepack verify to verify a package, and filepack serve to start an HTTP package server.

See Commands for all commands and their --help strings, or run filepack help for supported subcommands and filepack help SUBCOMMAND for information about a particular subcommand.

Creating Packages

To create a package in the current directory:

filepack create

The manifest, containing the hashes and sizes of all files in the current directory and its subdirectories, will be written to manifest.filepack.

To recreate a package in the current directory:

filepack create --force

Adding Package Metadata

Packages may optionally contain metadata in metadata.filemeta. This metadata describes the contents of the package, the package itself, and the media content of the package.

Metadata may be added by creating a metadata template in metadata.yaml:

echo "title: Fifty-three More Things to do in Zero Gravity" > metadata.yaml

Create a package and write the metadata to metadata.filemeta:

filepack create

Package metadata can be printed with:

filepack metadata

The metadata schema is extensive, with many fields and media types. See Metadata for more information.

Linting Packages

To create a package with all lints enabled:

filepack create --deny all

Individual lints may be disabled with --allow:

filepack create --deny all --allow windows-reserved-filename

Filepack supports a variety of lints. These include checks for cross-platform compatibility issues, like case-conflicts on case-insensitive filesystems; quality issues, like inclusion of junk files; and metadata issues, like missing or incomplete metadata. Lint groups, such as all, allow enabling or disabling multiple related lints.

Creating a package with all lints enabled and fixing them is a great way to learn more about Filepack and package metadata.

Lint and lint group can be printed with:

filepack lints

Verifying Packages

A package can be verified by manifest, fingerprint, or public key. Verification will fail if files have been added, removed, or modified. The three verification methods differ by what is trusted: the manifest, fingerprint, or private key corresponding to the public key.

The package in the current directory can be verified against the hashes and sizes in the manifest:

filepack verify

As long as the manifest has not been modified, any change to a file will cause filepack to exit with a non-zero exit code.

A package can also be verified by fingerprint, the root hash of the package Merkle tree.

First, print the fingerprint:

filepack fingerprint

Then, verify the package by fingerprint:

filepack verify --fingerprint <FINGERPRINT>

As long as the fingerprint has not been modified, any change to the package will cause filepack to exit with a non-zero exit code.

Signing Packages

Generate a new key pair with the default name master:

filepack keygen

Keys are stored in the keychain subdirectory of the Filepack data directory.

Sign the package with the newly generated private key:

filepack sign

Print the newly generated public key:

filepack key

And finally, verify that the package was signed by your private key:

filepack verify --key <PUBLIC_KEY>

Any change to the package will cause filepack to exit with a non-zero exit code. As long as your private key is secure, nobody can create a signature which verifies against your public key.

Packages may also be signed at creation:

filepack create --sign

To serve packages locally on port 8000, with unrestricted writes:

filepack serve --http-port 8000 --unrestricted-writes

Upload the package in the current directory and print its server-assigned package number with:

filepack upload --server 127.0.0.1:8000

Open http://127.0.0.1:8000 in your web browser to view packages. Media items in packages with media metadata can be viewed and played.

Download the uploaded package to a new directory with:

filepack download --server 127.0.0.1:8000 --package <FINGERPRINT> <DIRECTORY>

Delete the package from the server with:

filepack delete --server 127.0.0.1:8000 <PACKAGE_NUMBER>

Run garbage collection to clean up files no longer referenced by any package:

filepack gc --server 127.0.0.1:8000

See Server for more information.

Keyboard shortcuts