homelabctl

    __                         __      __         __  __
   / /_  ____  ____ ___  ___  / /___ _/ /_  _____/ /_/ /
  / __ \/ __ \/ __ `__ \/ _ \/ / __ `/ __ \/ ___/ __/ /
 / / / / /_/ / / / / / /  __/ / /_/ / /_/ / /__/ /_/ /
/_/ /_/\____/_/ /_/ /_/\___/_/\__,_/_.___/\___/\__/_/

A CLI tool for managing homelab infrastructure, built on radp-bash-framework.

Table of Contents

• Features
• Requirements
• Supported Platforms
• Installation
• Quick Start
• Commands
• Global Options
• Shell Completion
• Documentation
• Contributing

Features

• Vagrant Integration - Passthrough to Vagrant commands with automatic Vagrantfile detection
• RADP Vagrant Framework - Initialize, configure, and manage multi-VM environments
• Software Setup - Install 50+ CLI tools, languages, and DevOps tools across platforms
• Profiles - Batch install packages via profiles for reproducible environments
• Shell Completion - Bash and Zsh completion with dynamic suggestions

Requirements

• Bash 4.0+ (macOS users: brew install bash)
• Git (for manual installation)
• radp-bash-framework (auto-installed by install script)

Supported Platforms

OS	Architecture	Package Manager	Notes
macOS	Intel (x86_64), Apple Silicon	Homebrew	Requires bash from Homebrew
Fedora/RHEL/CentOS	x86_64, aarch64	DNF/YUM (COPR)	RHEL 8+, Fedora 38+
Ubuntu/Debian	amd64, arm64	APT (OBS)	Ubuntu 20.04+, Debian 11+
openSUSE	x86_64	Zypper (OBS)	Tumbleweed, Leap 15.4+

Installation

Quick Install

curl -fsSL https://raw.githubusercontent.com/xooooooooox/homelabctl/main/install.sh | bash

Homebrew (macOS)

brew tap xooooooooox/radp
brew install homelabctl

RPM (Fedora/RHEL/CentOS)

sudo dnf copr enable -y xooooooooox/radp
sudo dnf install -y radp-bash-framework homelabctl

Portable Binary

Download a self-contained portable binary from GitHub Releases:

# macOS Apple Silicon
curl -fsSL https://github.com/xooooooooox/homelabctl/releases/latest/download/homelabctl-portable-darwin-arm64 -o homelabctl
chmod +x homelabctl
./homelabctl --help

# Linux x86_64
curl -fsSL https://github.com/xooooooooox/homelabctl/releases/latest/download/homelabctl-portable-linux-amd64 -o homelabctl
chmod +x homelabctl
./homelabctl --help

Note: Portable binary requires radp-bash-framework to be installed.

See Installation Guide for more options including Debian/Ubuntu, manual installation, and upgrading.

Quick Start

# Show help
homelabctl --help

# Install development tools
homelabctl setup install fzf
homelabctl setup install nodejs -v 20
homelabctl setup profile apply recommend

# Manage Vagrant VMs (requires radp-vagrant-framework)
homelabctl vf init myproject --template k8s-cluster
homelabctl vf vg up

Commands

Vagrant Integration (vf)

Command	Description
vf vg <cmd>	Vagrant command passthrough
vf init [dir]	Initialize a vagrant project
vf list	List clusters and guests
vf info	Show radp-vagrant-framework info
vf validate	Validate YAML configuration
vf dump-config	Export merged configuration
vf generate	Generate standalone Vagrantfile
vf template list/show	List or show templates
vf version	Show framework version

Target VMs by cluster (instead of full machine names):

homelabctl vf vg up -C my-cluster # All VMs in cluster
homelabctl vf vg up -C my-cluster -G 1,2 # Specific guests
homelabctl vf vg up -C cluster1,cluster2 # Multiple clusters

Requires radp-vagrant-framework. See Vagrant Guide for details.

Software Setup (setup)

Command	Description
setup list	List available packages
setup info <name>	Show package details
setup deps <name>	Show dependency tree
setup install <name>	Install a package
setup profile list	List available profiles
setup profile show <name>	Show profile details
setup profile apply <name>	Apply a profile
setup configure list	List system configurations
setup configure <name>	Run a configuration task

Available categories: system, shell, editors, languages, devops, vcs, security, search, dev-tools, utilities

System configurations: chrony, expand-lvm, gpg-import, gpg-preset, yadm

See Setup Guide for architecture details, full package list, and custom extensions.

Global Options

Option	Description
-v, --verbose	Enable verbose output (banner + info logs)
--debug	Enable debug output (banner + debug logs)
--config	Show configuration (paths, settings, log)
--config --all	Include extension configurations
-h, --help	Show help
--version	Show version

By default, homelabctl runs in quiet mode (no banner, only error logs).

Shell Completion

Shell completion is automatically configured during installation. To regenerate manually:

# Bash
mkdir -p ~/.local/share/bash-completion/completions
homelabctl completion bash >~/.local/share/bash-completion/completions/homelabctl

# Zsh
mkdir -p ~/.zfunc
homelabctl completion zsh >~/.zfunc/_homelabctl

VF Completion

The homelabctl vf command supports dynamic completion for cluster names, guest IDs, and machine names. Config is automatically read from homelabctl's config file:

# ~/.config/homelabctl/config.yaml
radp:
  extend:
    homelabctl:
      vf:
        config_dir: $HOME/.config/homelabctl/vagrant

This allows completion to work without specifying -c on command line:

homelabctl vf vg --cluster <tab> # Shows cluster names
homelabctl vf vg --cluster dev -G <tab> # Shows guest IDs

Documentation

• Getting Started - Quick start guide
• Installation Guide - Full installation options, upgrade, uninstall
• Setup Guide - Package installation, profiles, custom extensions
• Vagrant Guide - VM management, templates, configuration
• CLI Reference - Complete command reference
• Configuration - YAML configuration system

Related Projects

• radp-bash-framework - Bash engineering & CLI framework ( dependency)
• radp-vagrant-framework - YAML-driven Vagrant framework

Contributing

See CONTRIBUTING.md for development setup, adding packages, and release process.

License

MIT