npm - homelab-tui - Versions diffs - 1.1.13 → 2.0.2 - Mend

homelab-tui 1.1.13 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +172 -104
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,70 +1,117 @@
-<div align="center">
+<p align="center">
+  <img src="docs/public/logo.svg" width="88" height="88" alt="homelab-tui logo">
+</p>
-# 🖥️ homelab-tui
+<h1 align="center">homelab-tui</h1>
-**A cross-platform terminal UI for monitoring your homelab over SSH**
+<p align="center">
+  A fast, keyboard-first terminal interface for monitoring and controlling homelab hosts over SSH.
+</p>
-[![Bun](https://img.shields.io/badge/Bun-000000?style=for-the-badge&logo=bun&logoColor=white)](https://bun.sh)
-[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![React](https://img.shields.io/badge/React%20Ink-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://github.com/vadimdemedes/ink)
-[![npm](https://img.shields.io/npm/v/homelab-tui?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/homelab-tui)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://github.com/ACHRAF-YOUSSEF/homelab-tui/blob/main/LICENSE)
+<p align="center">
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-000000?style=for-the-badge&logo=bun&logoColor=white" alt="Bun"></a>
+  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"></a>
+  <a href="https://opentui.com/"><img src="https://img.shields.io/badge/React%20OpenTUI-61DAFB?style=for-the-badge&logo=react&logoColor=black" alt="React OpenTUI"></a>
+  <a href="https://www.npmjs.com/package/homelab-tui"><img src="https://img.shields.io/npm/v/homelab-tui?style=for-the-badge&logo=npm&logoColor=white" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="MIT license"></a>
+</p>
-[![Linux](https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black)]()
-[![macOS](https://img.shields.io/badge/macOS-000000?style=for-the-badge&logo=apple&logoColor=white)]()
-[![Windows](https://img.shields.io/badge/Windows-0078D4?style=for-the-badge&logo=windows&logoColor=white)]()
+<p align="center">
+  <img src="https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Linux">
+  <img src="https://img.shields.io/badge/macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="macOS">
+  <img src="https://img.shields.io/badge/Windows-0078D4?style=for-the-badge&logo=windows&logoColor=white" alt="Windows">
+</p>
-<p>
-  <a href="https://github.com/ACHRAF-YOUSSEF">
-    <img src="https://img.shields.io/badge/Author-Achraf%20Youssef-181717?style=for-the-badge&logo=github" />
-  </a>
-  <a href="https://achraf-youssef.github.io/portfolio/">
-    <img src="https://img.shields.io/badge/Portfolio-Visit-blueviolet?style=for-the-badge&logo=firefox" />
-  </a>
+<p align="center">
+  <a href="https://github.com/ACHRAF-YOUSSEF"><img src="https://img.shields.io/badge/Author-Achraf%20Youssef-181717?style=for-the-badge&logo=github" alt="Author: Achraf Youssef"></a>
+  <a href="https://achraf-youssef.github.io/portfolio/"><img src="https://img.shields.io/badge/Portfolio-Visit-blueviolet?style=for-the-badge&logo=firefox" alt="Portfolio"></a>
 </p>
-> Discovers Docker containers and running programs (Jellyfin, Ollama, LM Studio, game servers…), streams live logs, and shows system metrics — all over SSH. Supports Linux, macOS, and Windows remote hosts.
+<p align="center">
+  <a href="https://achraf-youssef.github.io/homelab-tui/">Documentation</a>
+  ·
+  <a href="https://github.com/ACHRAF-YOUSSEF/homelab-tui/releases">Releases</a>
+  ·
+  <a href="https://github.com/ACHRAF-YOUSSEF/homelab-tui/issues">Issues</a>
+</p>
-</div>
+![homelab-tui service monitoring and live logs](assets/logs.png)
----
+homelab-tui connects to Linux, macOS, and Windows hosts over SSH, discovers Docker containers and native services, displays system metrics and logs, and provides guarded service controls from one terminal.
+## Features
+- **Multi-host monitoring** — open several independent SSH connections in responsive panes.
+- **Docker and Compose discovery** — inspect status, image, ports, health, and Compose projects.
+- **Native service discovery** — find programs listening on TCP ports across supported operating systems.
+- **System metrics** — monitor CPU, memory, and disk usage without installing a remote agent.
+- **Live logs** — follow Docker logs and supported native-process logs over SSH.
+- **Keyboard-first controls** — search, filter, sort, restart, stop, start, and switch panes without a mouse.
+- **Resilient connections** — keep healthy hosts usable while another host reconnects or fails.
+- **Secure authentication** — use passwords, private keys, encrypted keys, or an SSH agent.
+- **Self-update support** — check for and install new GitHub releases from the CLI.
 ## Install
+### npm
 ```sh
 npm install -g homelab-tui
+homelab-tui
 ```
-The correct binary for your platform is downloaded automatically on install. No Bun runtime needed.
+The npm package installs the compiled binary for your operating system and CPU architecture. Bun is not required after installation.
-## Usage
+### Bun
+Bun requires packages with lifecycle scripts to be trusted:
+```sh
+bun add -g homelab-tui
+bun pm trust homelab-tui
+bun add -g homelab-tui
+```
+### Prebuilt binary
+Download the latest binary from [GitHub Releases](https://github.com/ACHRAF-YOUSSEF/homelab-tui/releases).
+| Platform | File |
+|---|---|
+| Linux x64 | `homelab-tui-linux-x64` |
+| Linux arm64 | `homelab-tui-linux-arm64` |
+| macOS Intel | `homelab-tui-darwin-x64` |
+| macOS Apple Silicon | `homelab-tui-darwin-arm64` |
+| Windows x64 | `homelab-tui-windows-x64.exe` |
+### Build from source
 ```sh
-homelab-tui                                        # launch TUI
-homelab-tui --config /path/to/homelab.config.json  # use a specific config (session only)
-homelab-tui --set-config /path/to/homelab.config.json  # persist config path as default
-homelab-tui --update                               # self-update to latest release
-homelab-tui --check-update                         # check latest version without installing
-homelab-tui --version                              # print version
-homelab-tui --help                                 # print help
+git clone https://github.com/ACHRAF-YOUSSEF/homelab-tui.git
+cd homelab-tui
+bun install
+bun run dev
 ```
-On first launch, a setup wizard lets you create or locate your `homelab.config.json`.
+## Quick start
-## Config
+Create `homelab.config.json`:
 ```json
 {
   "hosts": [
     {
-      "name": "desktop",
-      "host": "192.168.1.20",
+      "name": "server",
+      "host": "192.168.1.10",
       "port": 22,
-      "username": "achraf",
-      "authMethod": "password",
+      "username": "admin",
+      "authMethod": "key",
+      "privateKeyPath": "~/.ssh/id_ed25519",
+      "group": "home",
+      "refreshInterval": 3000,
       "discovery": {
         "docker": true,
-        "nativeServices": false,
+        "nativeServices": true,
         "includeStoppedContainers": true
       }
     }
@@ -72,80 +119,101 @@ On first launch, a setup wizard lets you create or locate your `homelab.config.j
 }
 ```
-| Field | Description |
-|---|---|
-| `authMethod` | `"password"` (prompted at launch) or `"key"` (SSH private key, supports agent) |
-| `group` | Optional label to group hosts in the selector (filter with `g`) |
-| `refreshInterval` | Polling interval in ms (default `3000`, min `1000`, max `60000`) |
-| `nativeServices` | Discover processes listening on TCP ports (Jellyfin, Ollama, LM Studio, game servers…) |
-| `includeStoppedContainers` | Show stopped Docker containers |
+Then launch:
-## Keyboard shortcuts
+```sh
+homelab-tui
+```
-### Host selector
+Passwords and private-key passphrases are prompted at launch and are never stored in the configuration file. See the [configuration guide](https://achraf-youssef.github.io/homelab-tui/guide/configuration) for every field and default.
+## Usage
 | Key | Action |
-|-----|--------|
-| `↑` / `↓` | Select host |
-| `Enter` | Connect to selected host |
-| `m` | Multi-host mode (select multiple hosts) |
-| `Esc` | Back to previous monitor view (when coming from one) |
-| `a` | Add new host |
-| `e` | Edit selected host |
-| `d` | Delete selected host |
+|---|---|
+| `↑` / `↓` | Select a host or service |
+| `Enter` | Connect or confirm |
+| `Tab` / `Shift+Tab` | Focus the next or previous host pane |
+| `/` | Search services |
+| `f` | Cycle filters |
+| `o` | Cycle sorting |
+| `r` | Restart the selected service |
+| `s` | Stop a container or kill a native process |
+| `t` | Start a Docker container |
+| `l` | Toggle live logs |
+| `a` / `x` | Add or close a host pane |
+| `h` | Return to the host selector |
+| `q` | Quit |
-In multi-host mode: `Space` to check/uncheck, `Enter` to open all in split-pane, `Esc` to cancel.
+The footer uses the same key definitions as the input handlers and adapts to the selected service. See the complete [keybinding reference](https://achraf-youssef.github.io/homelab-tui/guide/keybindings).
-### Monitor
+## Command line
-| Key | Action |
-|-----|--------|
-| `↑` / `↓` | Select service |
-| `r` | Restart selected Docker container |
-| `s` | Stop selected Docker container / kill selected process |
-| `t` | Start selected Docker container |
-| `l` | Toggle live log panel |
-| `PgUp` / `PgDn` | Scroll log panel |
-| `a` | Add another host as a new pane (stays connected) |
-| `x` | Close the focused pane |
-| `<` / `>` | Move focused pane left / right (swap, connections stay alive) |
-| `Tab` / `Shift+Tab` | Switch focused pane |
-| `/` | Search by name or image |
-| `f` | Cycle filter: all → docker → processes → running → stopped → failed → restarting |
-| `o` | Cycle sort: name → status → image |
-| `h` | Switch host |
-| `q` | Quit |
+| Option | Description |
+|---|---|
+| `--config <path>`, `-c <path>` | Use a configuration file for this run |
+| `--set-config <path>` | Save the default configuration path |
+| `--check-update` | Compare the installed and latest versions |
+| `--update` | Download and install the latest release |
+| `--version`, `-v` | Print the installed version |
+| `--help`, `-h` | Print command help |
+## Supported hosts
+| Capability | Linux | macOS | Windows |
+|---|:---:|:---:|:---:|
+| System metrics | ✓ | ✓ | ✓ |
+| Docker containers | ✓ | ✓ | ✓ |
+| Native process discovery | ✓ | ✓ | ✓ |
+| Native log streaming | `journalctl` | `log stream` | — |
+| Native process restart | systemd | — | — |
+Remote hosts need an SSH server and standard system utilities. Docker is only required for container discovery and controls. Windows hosts require [OpenSSH Server](https://learn.microsoft.com/windows-server/administration/openssh/openssh_install_firstuse).
+## Documentation
+- [Installation](https://achraf-youssef.github.io/homelab-tui/guide/install)
+- [Configuration](https://achraf-youssef.github.io/homelab-tui/guide/configuration)
+- [Monitoring](https://achraf-youssef.github.io/homelab-tui/guide/monitoring)
+- [Keybindings](https://achraf-youssef.github.io/homelab-tui/guide/keybindings)
+- [Command line](https://achraf-youssef.github.io/homelab-tui/guide/cli)
+- [Troubleshooting](https://achraf-youssef.github.io/homelab-tui/guide/troubleshooting)
+## Built With
+- [Bun](https://bun.sh/) — runtime, package manager, test runner, and native binary compiler
+- [TypeScript](https://www.typescriptlang.org/) — strict application code
+- [React](https://react.dev/) — declarative interface components
+- [OpenTUI](https://opentui.com/) — native terminal renderer with React bindings
+- [node-ssh](https://github.com/steelbrain/node-ssh) — SSH connections, commands, and log streams
+- [Zod](https://zod.dev/) — configuration validation
+- [VitePress](https://vitepress.dev/) — documentation site
+## Development
-> Footer hints adapt to selection: Docker shows `r restart · s stop · t start`; processes show `r restart · s kill` (`r` uses systemd on Linux).
+```sh
+bun install
+bun run dev
+bun test
+bunx tsc --noEmit
+bun run build:linux-x64
+bun run docs:dev
+```
-## Features
+Contributions are welcome. Please open an issue before a large behavioral change and run the relevant checks before submitting a pull request.
+## License
+homelab-tui is released under the [MIT License](LICENSE).
+Copyright © 2026 [Achraf Youssef](https://github.com/ACHRAF-YOUSSEF).
+## Star History
-- **Multi-host split-pane** — monitor multiple hosts simultaneously side-by-side; compact per-pane headers with inline metrics; app bar shows all pane statuses; `Tab` to switch focus
-- **Host groups** — tag hosts with `"group"` in config; press `g` in the selector to filter by group
-- **Configurable refresh interval** — set per-host polling rate (`"refreshInterval": 5000`)
-- **Service-down alerts** — audible bell + red banner on running → stopped/failed transitions
-- **Disk full warnings** — ⚠ badge on disks above 85%
-- **Compose stack restart** — `r` on a Compose service opens a scope picker (container vs whole stack)
-- **Docker discovery** — containers with status, image, ports, health, Compose project
-- **Process discovery** — finds programs listening on TCP ports (Jellyfin, Ollama, LM Studio, game servers…) on Linux, macOS, and Windows
-- **Context-aware controls** — Docker: restart/stop/start; discovered processes: kill + restart via systemd (Linux)
-- **Live logs** — `docker logs -f` streamed over SSH; discovered processes stream via `journalctl -f` (Linux) or `log stream` (macOS); scrollable with auto-follow
-- **System metrics** — CPU %, RAM, disk usage
-- **Auth error handling** — wrong password shows an error and re-prompts immediately without leaving the app
-- **Auto-reconnect** — SSH keepalive detects silent drops (15 s interval, 3 missed → reconnect); exponential backoff (3 → 5 → 10 → 20 → 30 s); attempt counter shown in header
-- **Command timeout** — SSH commands time out after 30 s so a hanging command never blocks the refresh loop
-- **Self-update** — `homelab-tui --update` checks version first, skips download if already up to date; otherwise replaces the binary in place with a live progress bar
-- **Update notifications** — checks for a newer release on launch using proper semver comparison; shows `↑ vX.Y.Z available` in the app bar only when an actual upgrade exists
-## Supported platforms
-| Platform | Architecture |
-|----------|-------------|
-| Linux | x64, arm64 |
-| macOS | x64, arm64 (Apple Silicon) |
-| Windows | x64 |
-## Links
-- [GitHub](https://github.com/ACHRAF-YOUSSEF/homelab-tui)
-- [Report an issue](https://github.com/ACHRAF-YOUSSEF/homelab-tui/issues)
+<a href="https://www.star-history.com/?repos=ACHRAF-YOUSSEF%2Fhomelab-tui&type=timeline&legend=top-left">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=ACHRAF-YOUSSEF/homelab-tui&type=timeline&theme=dark&logscale&legend=top-left">
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=ACHRAF-YOUSSEF/homelab-tui&type=timeline&logscale&legend=top-left">
+    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=ACHRAF-YOUSSEF/homelab-tui&type=timeline&logscale&legend=top-left">
+  </picture>
+</a>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "homelab-tui",
-  "version": "1.1.13",
+  "version": "2.0.2",
   "description": "Terminal UI for monitoring a remote homelab server over SSH",
   "homepage": "https://github.com/ACHRAF-YOUSSEF/homelab-tui",
   "repository": {