← braid

braid tui

Interactive terminal dashboard showing pool state, disk health, allocation, scrub status, and active alerts.

When to use it

• Quick visual overview of your NAS health.
• Checking disk-level detail (LUKS cipher, SMART health, error counts, transport).
• Monitoring during or after a scrub.

Basic example

sudo braid tui

Demo mode

Try the TUI without a real pool (no config or btrfs required, no root required):

braid tui --demo

Demo mode shows three fake disks with sample data, useful for exploring the interface.

Flags

Keybindings

What it shows

Main view – pool status, mount point, capacity bar, balance state, and active alerts and advisories. When an alert is active, the banner lists each cause beneath it; latched causes use the same first-detected timestamp and relative-age format as braid status.

Refreshing – while the pool is mounted, pool, disk, scrub, and alert data refresh automatically about every 10 seconds and immediately when you press r. While the pool is not mounted, that data stays manual-only via r. When enabled, Fans and UPS telemetry also refresh automatically every 5 seconds and immediately on r. The footer’s Reload: r spinner and idle (Xms) duration reflect pool refreshes, including automatic pool refreshes; automatic Fans/UPS polls do not update it. The view redraws periodically while idle so relative ago times stay current.

Disk table – one row per disk: number, name, bus (sata/usb/nvme), SMART health, temperature, btrfs device-error count, and allocated (shown as percent used and allocated/size).

Disk status cell – when a declared disk is not assembled into the live pool, its row drops the allocation columns and shows a status cell instead. Cell color reflects severity: red marks identity, header, or mapper faults that need attention now; yellow marks the remaining diagnostic states, which can still need follow-up – missing in particular means a member is absent and the pool may be running degraded. The five states braid status also reports per-disk (missing, offline, unknown, uuid mismatch, LUKS header unreadable) carry fuller descriptions under braid status per-disk detail, with an Action: hint where applicable (missing, uuid mismatch, LUKS header unreadable; offline and unknown get none); the two TUI-only probe faults (mapper conflict, LUKS<v> (unsupported)) appear there only as config-disk probe-fault advisories. Run braid doctor to diagnose the states it covers – uuid mismatch, LUKS header unreadable, offline, and missing.

• missing (yellow) – the device is absent at its by-id path.
• offline (yellow) – present and LUKS-identity-verified, but not assembled into the live pool. Cause-neutral (a locked member of a degraded mount, an interrupted post-commit step, etc.); see decision 024.
• unknown (yellow) – braid could not classify the disk’s state.
• uuid mismatch (red) – the on-disk LUKS UUID differs from the recorded member: the disk was swapped, cloned, or reformatted. Run braid doctor for the expected vs observed UUID.
• mapper conflict (red) – the braid-<name> device-mapper node is open for the wrong backing device or LUKS UUID. Close it and unlock again.
• LUKS header unreadable (red) – the device is present but its LUKS header could not be read or validated.
• LUKS<v> (unsupported) (red) – the device holds a LUKS header of the wrong version (e.g. LUKS1; braid requires LUKS2). Back up its data and re-add the disk.

Fans (when fan control is enabled) – Data-tab row with a daemon: header annotation for hddfancontrol-braid.service: active is green, activating and inactive are yellow, failed is red, and unknown is gray. The annotation is not a column; the columns are PWM (raw/255 plus percent), RPM, Driving (the hottest drive and its temperature), and Curve. See the fan control guide.

UPS (when UPS support is enabled) – Data-tab row with the same daemon: header annotation for the NUT daemon. The columns are Status (color-coded flags), Battery, Runtime, and Load. See the UPS guide for Status severity.

Disk detail popup (press Enter on a disk) – disk name, LUKS lock status, cipher, key size, keyslot count, an allocations table (type/profile/size plus unallocated), the btrfs device-error breakdown (read/write/flush/corruption/generation), and a SMART section with the health verdict plus its supporting evidence rows (per-protocol: SATA reallocated/pending/uncorrectable, or NVMe critical-warning/media-errors/available-spare/percentage-used). A row for an out-of-spec attribute is colored red. Temperature is not repeated here – it has its own column in the disk table.

Tabs – three tabs, switched with Tab / Shift-Tab:

• Data (default) – pool allocation breakdown, disk table, capacity bar, plus Fans and UPS rows when enabled.
• Scrub – per-device scrub state, progress, and timing.
• Browse – raw CLI output inspector across five tool families: Btrfs, NUT (UPS), Systemd, SMART (smartctl), and lsblk. Btrfs views include filesystem usage/show/df/commit-stats, device usage/stats, subvolumes with drill-in plus raw full/snapshot/deleted/default views, scrub status/limits, balance status, quota status/qgroups, and inspect-internal chunks. UPS views include status, raw variables, supported instant commands, connected clients, settable variables, and UPS discovery. Systemd views include unit status, show, braid units, failed units, timers, and mounts. SMART views include device scan, health, info, attributes, and self-test/error logs. lsblk views include tree, filesystems, disks, all-columns, and SCSI. NUT > UPSes can help find the correct ups.name before UPS support is enabled.

Related commands

• status – non-interactive pool health output
• ups status – non-interactive UPS state output