Docs: CLI Reference

Documentation

CLI Reference

The Recipe CLI uses one engine for OS-building recipes and user-managed software. It runs each recipe on the host when it starts no program and in an isolated Ginux domain otherwise (the Recipe page explains which), publishes their named outputs, and activates a declared package output unless --no-activate is selected. See Post-Installation for the ripgrep workflow and the Recipe README for runtime setup on a development host.

Commands

CommandBehavior
recipe download RECIPEThe download step only: fetch the sources and pins into the download store.
recipe build RECIPEDownload what is missing, then build. Does not install.
recipe install RECIPERun every missing step, publish outputs and activate a declared package directory, then clean up unless --keep. --no-activate keeps producer-only behavior.
recipe update PACKAGEInstall the version the recipe as fetched names, replacing the installed one. Never edits a recipe.
recipe remove PACKAGERemove the installed files using the receipt, then whatever is left of the program's downloads and build material. --keep removes only the installed program.
recipe cleanup [RECIPE]Delete a program's downloads and build material (every program's without a name); the installed program stays. --downloads or --build limits it; --logs deletes the diagnostic logs.
recipe state RECIPEPrint the program's state: none, downloaded, built or installed.
recipe installedList active package receipts without executing recipes or starting Ginux.
recipe updatesTell which installed programs have a different version in their recipe; --upstream also asks whether upstream has a newer one. Only tells; changes nothing.
recipe storageReport what each program holds on disk.
recipe historyList installs, updates, removals and releases.
recipe listList recipe files and declared metadata, not installed applications; does not run setup.
recipe info RECIPEShow declared/inherited metadata; dynamic values are unavailable.
recipe hash FILECompute SHA256, SHA512 and BLAKE3.
recipe validate RECIPEValidate declarations, dependency inputs and derived contracts without running the recipe.
recipe inspect RECIPEInspect declared authority and typed inputs/outputs.
recipe explain RECIPEExplain effective authority, narrowing and denial provenance.
recipe diff BEFORE AFTERCompare declared/effective contracts and dependency authority.

RECIPE is a path to a .rhai file or a name, with .rhai appended if needed. Default lookup checks $XDG_DATA_HOME/recipe/recipes (normally ~/.local/share/recipe/recipes) before the shipped /usr/share/recipe/recipes; a local recipe overrides the same name. --recipes-path or RECIPE_PATH selects only that collection. Run recipe --help and recipe <command> --help for the full syntax.

User Package Lifecycle

recipe update ripgrep installs the version the recipe as fetched names, in place of the installed one. Recipe only tells that upstream has a newer version (recipe updates --upstream); it never changes a recipe and never installs a version the recipe does not name. An update is asked for one program at a time.

After a successful install Recipe deletes the downloads, the unpacked source, the build material and the saved state. --keep on install, update or build keeps them, and the choice is remembered per program; --no-keep turns it off. recipe remove frees the program's space at once: there are no earlier versions to keep. When a step fails, Recipe reports the failure; what to do about it is the user's call.

The active profile is <package-root>/profile; put <package-root>/profile/bin on PATH. remove uses the active receipt, so a changed or missing recipe and unavailable Ginux runtime do not prevent removing an installed package.

An image built by the current OS builder supplies /usr/libexec/recipe/ginux and /usr/share/recipe/runtime/rootfs.tar with its digest reference in root-reference. Explicit GINUX_BIN, GINUX_ROOTFS and GINUX_ROOT selections override those defaults. The native launcher needs root bootstrap privileges; receipt inspection and removal do not start it. recipe runtime remove deletes the cached build image; it is fetched again when a recipe needs it.

Screenshot: Installed software.
Installed software. See each installed program and its version, with the actions available for it. Development preview with sample data. View full size
Screenshot: Software updates.
Software updates. Programs with a newer recipe in the collection are marked. An update is asked for one program at a time. Development preview with sample data. View full size

Inputs and Results

Shell
recipe install ./producer.rhai --no-activate \
  --input source=./offline-source \
  --build-dir .artifacts/work/example \
  --state-dir .artifacts/state/example \
  --json-output .artifacts/example.json

The producer must declare source as a directory in NEEDS.inputs and its returned products in NEEDS.outputs. Inputs are imported read-only and reach the recipe through INPUTS. A named target input seeds the output. Final JSON contains validated published host paths in outputs; diagnostics go to stderr. Published products retain coordinator ownership. User packages are activated from a validated publication in the active profile.

Execution Options

OptionPurpose
--recipes-path DIRSelect one recipe collection; disable the default catalog fallback.
--package-root DIRPackage receipts and profile storage; root defaults to /var/lib/recipe, other users to $XDG_DATA_HOME/recipe.
--no-activateKeep install/remove on the producer lifecycle; the OS builder passes this explicitly.
--keep / --no-keepKeep the downloads and build material after a successful install, remembered per program; --no-keep turns it off and deletes them at once.
--build-dir DIRLogical build destination and lock; default a stable directory under the state directory.
--state-dir DIRWhere resumable state is kept; default ~/.local/state/recipe.
--input NAME=PATHBind a declared input kind at /inputs/NAME; DEP::NAME binds a dependency input.
--json-output FILEWrite the final result JSON to a file instead of stdout.
--define KEY=VALUEA define the recipe declares in NEEDS.defines; not a host filesystem import.
--jobs NRequested jobs, 1–16, default 1.
--no-persist-stateDisable recovery while retaining managed execution/publication.
--timeout-secs NCap the recipe-declared deadline, including silent work, across the graph.
--memory-mib NCap each process's declared virtual address space, not total tree RAM.
--storage-max-objects N / --storage-max-bytes NExplicit writable filesystem bounds.
--network-host HOST:PORTRestrict declared endpoints across the graph; cannot add authority.
--no-networkRemove network authority from the complete dependency graph.
--network-max-bytes NLower each instance's declared cumulative byte budget.

Contracts use versioned configured catalog 1002. Numeric TCP endpoints do not isolate HTTP identities; normal TLS verification remains required. Resolution selects and records a deterministic bounded address subset. CPU affinity exposes real eligible IDs, configured sysinfo is zero-filled, and poll/events have bounded waits without general signal-mask/restart semantics. See the supported runtime limits. An interrupted build resumes from its newest checkpoint; to redo a step, clean it up and run it again. Diagnostics live under <state-root>/logs/<invocation-id>. Cancellation/deadline failures preserve the last complete checkpoint and cannot publish failed work.

Writing Recipes

See the Recipe Format and the author guide for the API 1 contract and a runnable example.