CLI reference: every command, every option.

list-targets

saphira-image list-targets

Prints the target matrix: name, boot method, init system and profile for every supported target. Needs nothing else and runs anywhere.

plan

saphira-image plan --target TARGET [--size SIZE]

Prints the exact partition plan for a target without building anything: no root privileges, no assembler, no repository needed. Inspect a plan on a machine that could never build an image.

--target NAME

One of the matrix targets.

--size SIZE

Minimum image size used to size the partitions (default 2G). Accepts K, M, G, T.

--arch ARCH

x86_64 (default) or aarch64. BIOS targets are refused on aarch64.

--allocate SIZE

Cap the initial partition layout; the remainder stays unallocated.

--esp-size MIB

ESP capacity: one of 64, 128, 256, 512, 768, 1024 (default 64).

--root-size SIZE

Exact root partition capacity (MiB/GiB/TiB, 1 MiB aligned, at least 32 MiB).

report

saphira-image report --target TARGET [--role ROLE]...

Resolves the composed profile statically against the repository index and reports the declared intentions without building anything. No package is built by this subcommand.

--target NAME

One of the matrix targets.

--role NAME

Add a role layer to the measured closure. Repeatable.

--role-file PATH

Add intentions from a file. Repeatable.

--size SIZE

Minimum image size used to size the partitions (default 2G).

build

saphira-image build --target TARGET --output IMAGE [options]

Partitions a disk image, installs Saphira through the canonical installer, prepares the init system, installs the bootloader, and reports what went in. Needs root (loop devices and mounts).

--target NAME

A matrix target, or usb-installer for installer media.

--output PATH

Image path. A .raw suffix produces a raw image; .qcow2 converts through qemu-img (qemu required). An existing path is refused, never overwritten.

--size SIZE

Total capacity of the image (default 2G). Accepts K, M, G, T.

--allocate SIZE

How much of that capacity the initial partition layout occupies: an absolute size (40G) or a percentage of --size (60%). The remainder is left unallocated for later growth. Omitted, the partitions occupy the whole capacity.

--esp-size MIB

ESP capacity in MiB: one of 64, 128, 256, 512, 768, 1024 (default 64). Below 64 is refused: FAT32 needs at least 65,525 data clusters. Larger sizes suit Windows coexistence and UKIs.

--root-size SIZE

Exact root partition capacity (MiB/GiB/TiB, 1 MiB aligned, at least 32 MiB). Omitted, root fills the allocation. Over-budget combinations are refused; nothing is resized silently.

--arch ARCH

Target architecture: x86_64 (default) or aarch64. Selects the repository architecture, the installed packages and the bootloader platform. Refused for combinations the platform does not have, such as BIOS on aarch64.

--repository PATH

Repository index (Packages.adb) to install from. Defaults to the host repository.

--hostname NAME

Hostname written into the image (default saphira on OpenRC targets, saphirad on systemd targets).

--root-password PW

Set the root password in the image.

--netconf LIST

Comma-separated IFACE:MODE (dhcp|off) written as /etc/saphira-network.d/10-image-IFACE.conf. Empty (default) writes nothing.

--role NAME

Add a role layer. Repeatable.

--role-file PATH

Add intentions from a file. Repeatable.

--no-enable

Install the profile but enable none of its services.

--kernel-arg ARG

Append ARG to GRUB_CMDLINE_LINUX in the image. Repeatable; for what a deployment needs that the shipped default deliberately does not assume, such as console=ttyS0,115200.

--keep-work

Retain the scratch workspace for diagnosis when a build fails.

--report

Accepted. The full image report is printed at the end of every build anyway; this flag exists so you can copy verbatim the build command suggested by the report subcommand's output.

install-to-disk

saphira-image install-to-disk --target TARGET --device DEV [options]

Installs through the same engine onto a real disk instead of an image file: the same partition generator (sized to the whole device), the same installer and identity replay, the same init preparation and PARTUUID-stable bootloader. Only the backing differs.

--target NAME

One of the eight matrix targets. Installer media (usb-installer) is refused: it is an image, never an installed system.

--device DEV

Whole-disk block device to install onto (for example /dev/vdb on Hatchling; loop and nbd devices are accepted for disposable test disks). There is no default, no discovery and no --yes. A partition is refused, because the tool owns the whole table.

--preview

Print the complete installation plan and stop without touching the device.

--allocate SIZE

Partition only this much of the device (absolute or percentage, as in build); the remainder stays unallocated. Omitted, the whole device is used.

--esp-size MIB

ESP capacity in MiB: one of 64, 128, 256, 512, 768, 1024 (default 64).

--root-size SIZE

Exact root partition capacity (MiB/GiB/TiB); remainder stays unallocated. Omitted, root fills the allocation.

--hostname NAME

Hostname written into the system (default saphira on OpenRC targets, saphirad on systemd targets).

--root-password PW

Set the root password in the system.

--netconf LIST

Comma-separated IFACE:MODE (dhcp|off), as in build.

--role NAME

Add a role layer. Repeatable.

--role-file PATH

Add intentions from a file. Repeatable.

--arch ARCH

Target architecture: x86_64 (default) or aarch64.

--repository PATH

Repository index to install from. Defaults to the host repository.

--kernel-arg ARG

Append ARG to GRUB_CMDLINE_LINUX. Repeatable.

--no-enable

Do not enable the target's services.

--keep-work

Retain the scratch workspace on failure.

export

saphira-image export --image IMAGE --output ROOTFS.tar.xz

Packs the root filesystem of a finished image into a distributable bootstrap tarball. The image is the source of truth: export reads the built image, never a build workspace. Volatile and machine-unique state (machine-id, SSH host keys, logs, caches, first-boot state) is excluded by an explicit list, and a .sha256 checksum is written beside the archive. Needs root (nbd mount).

--image IMAGE

A finished image built by saphira-image.

--output PATH

Destination path. Must end in .tar.xz. An existing path is refused, never overwritten.