Flash disk images to USB drives (and other block devices) and clone devices back to image files. Litho ships a CLI (litho), an interactive terminal UI (litho-tui), and a Rust library used by the Lithographer desktop app.
Supported for full use: Linux and Windows. macOS is experimental.
| Requirement | |
|---|---|
| OS | Linux or Windows |
| Privileges | Root (sudo) on Linux, Administrator on Windows — for flash and clone only |
| Images | .img, .iso, or .img.xz |
| TUI terminal | At least 60×24 characters |
Querying devices does not require elevation.
If you only want the GUI, install Lithographer instead.
By default this crate builds in simulation mode (simulated-io): progress is shown but disks are not written. That keeps development and accidental installs safe.
For a real flash/clone tool, always pass --no-default-features --features real-io.
Crate name on crates.io: liblitho (binaries are still named litho and litho-tui).
# Required for real disk I/O
cargo install liblitho --no-default-features --features real-io
# Then:
sudo litho --help
litho-tui --helpWithout those flags, cargo install liblitho installs a simulation-only build (safe, but it will not write images to devices).
# Real disk I/O (what you want for actual flash/clone)
cargo build --release --no-default-features --features real-io --bin litho --bin litho-tui| Binary | Path |
|---|---|
| CLI | target/release/litho |
| TUI | target/release/litho-tui |
# Dev / tests only — simulation, no real writes
cargo build
cargo testAlways double-check the device path. Flashing the wrong disk destroys data.
# List devices (no root needed)
litho query
# Flash (Linux example)
sudo litho flash --file /path/to/image.img --device /dev/sdX
# Flash compressed image + verify write
sudo litho flash -f image.img.xz -d /dev/sdX --verify
# Clone a device to a file
sudo litho clone --device /dev/sdX --file /path/to/backup.img| Option | Meaning |
|---|---|
-f, --file |
Image path (flash source or clone output) |
-d, --device |
Block device (e.g. /dev/sdb, \\.\PhysicalDrive1) |
-b, --block-size |
I/O buffer size in bytes (default 4096) |
--verify |
After flash, read back and compare SHA-256 (flash only) |
-s, --silent |
Less progress output |
--dry-run |
Validate only; do not write |
--yes |
Confirm automatic volume unmount / dismount |
-o terminal|gui |
Human progress bar vs GUI sidecar protocol |
On Windows, confirm volume dismount in the TUI, or pass --yes on the CLI.
sudo ./target/release/litho-tui
# or unprivileged: you will be prompted to elevate (pkexec / UAC)
./target/release/litho-tui| Key | Action |
|---|---|
Tab |
Move between sections |
1 / 2 |
Flash / Clone mode |
d / f |
Device / file picker |
r |
Refresh devices |
Space |
Toggle verify (flash) |
Enter |
Activate focused control / start |
c / Esc |
Cancel running operation |
q |
Quit |
litho-tui --mode flash --device /dev/sdb --image ./image.img
litho-tui --help| Option | Description |
|---|---|
-m, --mode |
flash or clone |
-d, --device |
Pre-select device |
-i / -f |
Pre-fill image path |
--start |
Start immediately if already elevated |
--log-file |
Default: ~/.cache/litho/litho-tui.log (Windows: %LOCALAPPDATA%\litho\) |
--log-level |
error … trace (default info) |
- Prefer removable USB/SD media as the flash target when possible.
- Litho refuses the system disk, partitions (use the whole disk), and busy/mounted volumes until you confirm unmount/dismount.
- Cancel stops between I/O blocks; a cancelled flash may leave a partially written device.
For a graphical frontend, use Lithographer. It runs as a normal user app and elevates only the litho helper for flash/clone.
| Audience | Document |
|---|---|
| Developers (library API, architecture, platform modules, build flags, GUI protocol, portable builds) | docs/developer-docs.md |
| Platform trait design notes | docs/platform-segregation-plan.md |
| Changelog | CHANGELOG.md |
MIT — see Cargo.toml.