htdotfile
v1.4.1
Published
Cross-platform dotfile manager TUI powered by OpenTUI
Maintainers
Readme
HTDotFile
Cross-platform dotfile manager TUI powered by React and OpenTUI.
HTDotFile reads a portable YAML manifest, scans only configured paths, previews every filesystem change, and creates adjacent backups before replacing existing targets.
Version 1.4 adds a background tray daemon and repository divergence resolution.
Install With npm
HTDotFile can be installed directly from npm on Windows, Linux, and macOS:
npm install --global htdotfileThen run:
htdotThe alias htdotfile is also available.
Bun is declared as a dependency, so npm installs it automatically along with the package. No separate Bun installation is required.
Alternative Bun Install
You may also use Bun as the package manager:
bun install --global htdotfileBoth installation methods install the same npm package. HTDotFile declares Bun as a dependency, so it is installed automatically; OpenTUI selects its native renderer dependency for the current OS and CPU.
Usage
htdot
htdot --manifest /path/to/htdot.yaml
htdot --versionManifest selection order:
--manifestHTDOT_MANIFESThtdot.yamlin the current directory- The operating-system user configuration directory
Controls
| Input | Action |
| --- | --- |
| Up/Down, j/k | Select a dotfile |
| Mouse click | Select an item or button |
| Mouse wheel | Move through the list |
| p | Preview the selected change |
| Enter | Confirm an applicable preview |
| a | Open the preset library |
| e | Edit source and target paths |
| g | Open repository settings |
| r | Rescan configured paths |
| Esc | Cancel or close |
| q, Ctrl+C | Quit |
Safety
- Scanning is read-only.
- Apply requires a preview and explicit confirmation.
- The executor revalidates source and target state immediately before applying.
- Existing targets are renamed into a unique adjacent backup before replacement.
- Rollback failures report the retained backup path.
- Copy strategy currently supports regular files only.
Full documentation and source: https://github.com/Association-of-stupid-people/HTDotFileCLI
