📦 homebutler

Homeserver Management

Manage homelab servers using the homebutler 命令行工具. Single binary, no daemon/database required, JSON 输出, MCP-friendly.

Prerequisites

homebutler must be 安装ed and avAIlable in PATH.

# 检查 if 安装ed which homebutler

# Option 1: 安装 via Homebrew (macOS/Linux) brew 安装 Higangssh/homebutler/homebutler

# Option 2: 安装 via Go go 安装 github.com/Higangssh/homebutler@latest

# Option 3: Build from source git clone https://github.com/Higangssh/homebutler.git cd homebutler && make build && sudo mv homebutler /usr/local/bin/

Commands 设置up Wizard homebutler init # Interactive config 设置up

创建s a config file at ~/.config/homebutler/config.yaml with 图形界面ded prompts.

系统 状态 homebutler 状态 # Local server homebutler 状态 --server rpi # Specific remote server homebutler 状态 --all # All servers in parallel

Returns: hostname, OS, arch, uptime, CPU (usage%, cores), memory (total/used/%), disks (mount/total/used/%)

Butler 报告 homebutler 报告 # 健康, 警告s, changes, suggested actions homebutler 报告 --no-save # Preview without writing a snapshot homebutler 报告 --keep 7 # RetAIn latest 7 snapshots homebutler 报告 --json # Structured 输出 for 自动化/MCP

Use this first when the user asks “how is my homelab/server doing?” and wants a concise operational summary. It snapshots current 系统/contAIner/port 状态 and compares it with the previous 运行.

Inventory & Topo记录y homebutler inventory 扫描 # Tree view of 系统, contAIners, ports homebutler inventory 扫描 --json # Structured inventory homebutler inventory 导出 --格式化 mermAId # MermAId topo记录y diagram

Use this when the user asks what is 运行ning, which contAIner owns a port, or wants topo记录y/上下文 for docs or AI analysis.

Docker Management homebutler docker 列出 # 列出 all contAIners homebutler docker 列出 --server rpi # 列出 on remote server homebutler docker 列出 --all # 列出 on all servers homebutler docker re启动 # Re启动 a contAIner homebutler docker 停止 # 停止 a contAIner homebutler docker 记录s # Last 50 lines of 记录s homebutler docker 记录s 200 # Last 200 lines

Wake-on-LAN homebutler wake # Wake by MAC homebutler wake # Wake by config name homebutler wake 192.168.1.255 # Custom broadcast

Config names are defined in config under wake tar获取s.

Open Ports homebutler ports # Local homebutler ports --server rpi # Remote homebutler ports --all # All servers

Returns: protocol, 添加ress, port, PID, process name

Network 扫描 homebutler network 扫描

Discovers devices on the local LAN via ping sweep + ARP table. Returns: IP, MAC, hostname, 状态. Note: May take up to 30 seconds. Some devices may not 应用ear if they don't 响应 to ping.

TUI 仪表盘 homebutler watch # Live terminal 仪表盘 for all servers

Real-time 监控ing of all 配置d servers with auto-refresh. Shows CPU, memory, disk, docker contAIners in a terminal UI.

网页 仪表盘 homebutler serve # 启动 网页 仪表盘 on port 8080 homebutler serve --port 3000 # Custom port homebutler serve --demo # Demo mode with fake data (no real 系统 calls)

Browser-based 仪表盘 at http://localhost:8080. Read-only view of all servers, docker contAIners, alerts.

SSH Host Key Trust homebutler trust # Trust remote server's SSH host key homebutler trust --re设置 # 移除 old key and re-trust

TOFU (Trust On First Use) 模型. Required before first SSH connection to a new server.

升级 homebutler 升级 # 升级 local + all remote servers homebutler 升级 --local # 升级 only local binary

下载s latest release from GitHub and 安装s it. For remote servers, uses SSH to 升级.

Resource Alerts homebutler alerts # Local homebutler alerts --server rpi # Remote homebutler alerts --all # All servers

检查s CPU/memory/disk agAInst thresholds in config. Returns 状态 (ok/警告/critical) per resource.

部署 (Remote 安装ation) homebutler 部署 --server rpi # 下载 from GitHub Releases homebutler 部署 --server rpi --local ./homebutler # AIr-g应用ed: copy local binary homebutler 部署 --all # 部署 to all remote servers

安装s homebutler on remote servers via SSH. Auto-检测s remote OS/architecture. 安装 path priority: /usr/local/bin → sudo /usr/local/bin → ~/.local/bin (with PATH auto-registration in .性能分析/.bashrc/.zshrc).

应用 安装 homebutler 安装 列出 # 列出 avAIlable 应用s homebutler 安装 <应用> # 安装 an ap