REFERENCE · 03

The image tool, verb by verb.

The tfs command-line interface (CLI) works on virtual-filesystem images directly: it inspects, walks, and creates images, runs commands with the VFS injected, drafts jail needs from journals, and manages encrypted images. Package-level operations live in tebako-pkg.

Inspect: info.

tfs info <image> [--json] [--manifest] [--provides] [--requires] [--platforms]
               [--backend-json] [--verify]

The info document is the machine form; the section flags print one manifest section each; --verify validates the image.

Walk and read: ls, tree, cat, stat, extract, find.

tfs ls <path>  [-r] [-l]
tfs tree <path>
tfs cat <file>
tfs stat <path>
tfs extract <image> [-d <dest>]
tfs find <image> -name <glob>

ls -r recurses and -l prints the long form; extract defaults the destination to the current directory. Nothing is ever extracted by merely reading — cat, ls, tree, and stat serve straight from the image.

Create: mkimage.

tfs mkimage <dir> -o <image.tfs> [--format dwarfs|limnifs]

The verb builds a dwarfs or limnifs image from a directory with the in-process writer — no external tooling.

Run: exec.

tfs exec <image> -- <command> [args...]
tfs exec --compose <file.yaml> -- <command> [args...]

The verb runs a dynamic native command with the VFS injected through the preload shim; --compose takes a whole composition instead of a single image.

Draft: needs.

tfs needs <image> --from-journal <journal.log>

The verb drafts a payload needs: block from a record-mode journal — the discovery half of the jail workflow. The task walkthrough is the Set a jail policy guide.

Encrypted images: encrypt, decrypt, mount.

tfs encrypt <image> -o <out> --recipient <keyid> [--subtree <path>] [--rewrap --key <keyid>]
tfs decrypt <image> -o <out.tar> --key <keyid>
tfs mount <image> --key <keyid>

Encrypt is per-image opt-in; --rewrap --key rotates grants without touching the bulk. Decrypt writes a plaintext tar, and mount unlocks an encrypted image for a run.