# Litho
<p align="center">
<img src="docs/assets/banner-dark.jpg" alt="Litho / Lithographer banner" width="720">
</p>
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](https://github.com/girish946/lithographer) desktop app.
**Supported for full use:** Linux and Windows. macOS is experimental.
---
## What you need
| **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.
---
## Install / build (end users)
If you only want the GUI, install **[Lithographer](https://github.com/girish946/lithographer)** instead.
### Important: enable `real-io` for actual flash/clone
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`**.
### Install from crates.io (when published)
Crate name on crates.io: **`liblitho`** (binaries are still named `litho` and `litho-tui`).
```bash
# Required for real disk I/O
cargo install liblitho --no-default-features --features real-io
# Then:
sudo litho --help
litho-tui --help
```
Without those flags, `cargo install liblitho` installs a **simulation-only** build (safe, but it will not write images to devices).
### Build from source
```bash
# 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
```
| CLI | `target/release/litho` |
| TUI | `target/release/litho-tui` |
```bash
# Dev / tests only — simulation, no real writes
cargo build
cargo test
```
---
## Quick start — CLI
**Always double-check the device path.** Flashing the wrong disk destroys data.
```bash
# 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
```
### Common options
| `-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.
---
## Quick start — TUI
```bash
sudo ./target/release/litho-tui
# or unprivileged: you will be prompted to elevate (pkexec / UAC)
./target/release/litho-tui
```
### Everyday shortcuts
| `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 |
### Launch with options
```bash
litho-tui --mode flash --device /dev/sdb --image ./image.img
litho-tui --help
```
| `-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`) |
---
## Safety
- 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.
---
## GUI
For a graphical frontend, use **[Lithographer](https://github.com/girish946/lithographer)**. It runs as a normal user app and elevates only the `litho` helper for flash/clone.
---
## More documentation
| **Developers** (library API, architecture, platform modules, build flags, GUI protocol, portable builds) | [docs/developer-docs.md](docs/developer-docs.md) |
| Platform trait design notes | [docs/platform-segregation-plan.md](docs/platform-segregation-plan.md) |
| Changelog | [CHANGELOG.md](CHANGELOG.md) |
## License
MIT — see `Cargo.toml`.
