CLI Reference

All commands accept --help for usage.

onelf init

Scaffold a starter onelf.toml.

onelf init [-o FILE] [--binary PATH] [--force]

Flag	Default	Description
-o, --output	onelf.toml	Where to write the recipe
--binary	none	Seed name/command from this binary's basename
--force	false	Overwrite existing file

onelf build

Run bundle-libs + pack from a recipe.

onelf build [PATH] [-o FILE]

Arg / Flag	Default	Description
PATH	.	Directory or .toml file
-o, --output	[package.output]	Override recipe's output path

onelf run

Run an AppDir in place for dev iteration.

onelf run [PATH] [--command PATH] [--entrypoint NAME] [--bundle] [-- ARGS...]

Flag	Description
PATH	AppDir or .toml file (default .)
--command	Binary to exec, relative to AppDir
--entrypoint	Select a recipe-defined entrypoint
--bundle	Run bundle-libs from the recipe first
-- ARGS	Passed to the entrypoint

onelf pack

Pack a directory into an executable.

onelf pack DIRECTORY -o OUTPUT --command PATH [options]

Flag	Default	Description
-o, --output	required	Output file
--command	required	Path to main binary within DIRECTORY
--name	command basename	Package name
--entrypoint NAME=PATH		Add extra entrypoint (repeatable)
--default-entrypoint NAME		Select default entrypoint
--lib-dir DIR	[auto]	Library dir for LD_LIBRARY_PATH (repeatable)
--level N	12	Zstd compression level (0 to 22)
--block-size SIZE	256K	Bytes per payload block, K/M suffix allowed (4K to 32M)
--dict	false	Train shared zstd dictionary
--no-compress	false	Store payload raw, no zstd (overrides --dict)
--preload PATH		Library dlopen'd on every exec via onelf-env (repeatable, re-exec-safe)
--memfd	auto	Force memfd eligibility on
--no-memfd		Force memfd eligibility off
--working-dir MODE	inherit	inherit, package, or command
--update-url URL		zsync URL; enables update runtime
--update-key PATH		32-byte Ed25519 public key; required for self-update
--no-embed-updater	false	Record the update URL without embedding the updater (saves 1.36 MB)
--host-libs MODE	auto	auto, always, or never: expose the host's library dirs
--exclude GLOB		Exclude paths matching glob (repeatable)

onelf bundle-libs

Resolve and copy shared library dependencies.

onelf bundle-libs DIRECTORY [options]

Flag	Default	Description
--target PATH	all ELF	Analyze only this binary
--from-binary PATH		Copy binary into DIRECTORY/bin/ first
--lib-dir DIR	lib	Where to place bundled libs
--exclude PFX		Soname prefixes to skip (comma/repeat)
--include SONAME		Force-include this soname (comma/repeat)
--search-path DIR		Extra lib search dir (highest priority)
--dry-run	false	Report without copying
--no-recursive	false	Don't resolve transitive deps
--gl, --dri, --vulkan, --wayland, --gtk	auto	Framework bundlers. Auto-detect inspects both DT_NEEDED and versioned soname strings in the binary, so dlopen'd frameworks are picked up too
--no-gl, --no-dri, --no-vulkan, --no-wayland, --no-gtk	false	Force-off a framework, overriding auto-detection and the matching --* flag
--strip	false	Run strip --strip-unneeded
--strict-libc	false	Skip wrong-family libc libs
--scan-dlopen	false	Scan binary strings for common dlopen sonames
--dlopen SONAME		Extra sonames for --scan-dlopen (comma/repeat)
--sysroot DIR		Take the bundle's contents from this sysroot's package database; needs --target
--sysroot-optional PKG		Optional dependency to include from the sysroot (repeatable)
--platform-line FILE		Soname prefixes the host provides, one per line
--policy FILE		Glob patterns that never ship, one per line
--trace FILE		Paths a test run opened, one per line

onelf sysroot

Obtain and inspect pinned sysroots. See Bundling from a Sysroot.

onelf sysroot fetch SOURCE DIR
onelf sysroot info DIR
onelf sysroot pack-gl DIR -o FILE

Command	Description
fetch SOURCE DIR	Materialize a .tar or .tar.zst rootfs from a local path or an https:// URL into DIR
info DIR	Print the package count, file count and glibc version of a materialized sysroot
pack-gl DIR -o FILE	Pack a GL build for hosts without one from a tree holding lib/, share/vulkan/icd.d and friends, after verifying it is self-contained, and print the BLAKE3 hash to pin in platform.toml

onelf info

Show metadata.

onelf info BINARY

onelf list

List packaged files.

onelf list BINARY

onelf extract

Extract files from a packed binary.

onelf extract BINARY [-o OUT] [--file PATH ...]

Without --file, extracts everything to onelf_extracted/ (or -o). With one --file and -o -, pipes that file to stdout.

onelf verify

Recompute BLAKE3 of each file entry and compare against the manifest.

onelf verify BINARY

Exit 0 on match, 1 on mismatch.

onelf icon

Extract the bundled icon.

onelf icon BINARY [--entrypoint NAME] [-o FILE]

onelf desktop

Extract the bundled .desktop file.

onelf desktop BINARY [--entrypoint NAME] [-o FILE]

onelf integrate

Install desktop shortcut and icon for a packed binary.

onelf integrate BINARY [--entrypoint NAME]

Installs the icon to $XDG_DATA_HOME/icons/hicolor/ and a .desktop file to $XDG_DATA_HOME/applications/. The Exec=, TryExec=, and Icon= fields are patched automatically. If the package has no bundled desktop file, a minimal one is generated.

Flag	Description
--entrypoint	Entrypoint name (default: default entrypoint)

onelf unintegrate

Remove desktop shortcut and icon installed by integrate.

onelf unintegrate BINARY [--entrypoint NAME]

onelf key

Manage the Ed25519 keys that sign self-updates.

onelf key new [--secret PATH] [--public PATH]
onelf key show --secret PATH [-o PATH]

Flag	Default	Description
--secret PATH	onelf.key	Secret key file, created owner-only
--public PATH	onelf.pub	Public key file, 32 raw bytes for --update-key
-o, --output PATH	stdout	Where show writes the public key

new refuses to overwrite an existing key file.

onelf sign

Write the detached signature the runtime verifies before installing an update.

onelf sign BINARY --key PATH [-o PATH]

Flag	Default	Description
--key PATH		Secret key file from onelf key new
-o, --output PATH	derived from the package's update URL	Signature output path

The default output name comes from the update URL the package carries, because that is the only name the runtime requests: a package whose update URL is app.onelf.zsync needs its signature at app.onelf.zsync.sig. Signing refuses when the key does not match the one embedded in the package. See Self-Update for the full publish flow.

onelf cache

Manage the persistent cache: packages extracted by the cache mode, and the GL builds fetched for hosts without one. list shows both; gc removes packages and builds unused past the age threshold.

onelf cache list
onelf cache clear
onelf cache gc [--max-age DAYS]