https://github.com/casper-justus/homectl
homectl - CLI for operating homelab and cloud infrastructure
https://github.com/casper-justus/homectl
cli compose devops docker homectl homelab infrastructure raspberry-pi ssh typescript
Last synced: 14 days ago
JSON representation
homectl - CLI for operating homelab and cloud infrastructure
- Host: GitHub
- URL: https://github.com/casper-justus/homectl
- Owner: casper-justus
- License: mit
- Created: 2026-05-15T10:50:19.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-15T12:26:34.000Z (about 1 month ago)
- Last Synced: 2026-05-15T13:18:10.290Z (about 1 month ago)
- Topics: cli, compose, devops, docker, homectl, homelab, infrastructure, raspberry-pi, ssh, typescript
- Language: TypeScript
- Size: 129 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# homectl
**Operate your homelab and small cloud fleet from one terminal.**
homectl is a unified CLI for managing Docker/Compose workloads across multiple hosts — local machines, Raspberry Pis, VPS instances, and cloud VMs — all through a single YAML config and SSH-first architecture.
## Install
```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/casper-justus/homectl/main/install.sh | bash
```
```powershell
# Windows (PowerShell)
iwr -useb https://raw.githubusercontent.com/casper-justus/homectl/main/install.ps1 | iex
```
The script auto-detects your OS, installs Node.js if missing, downloads the latest homectl, builds it, and links it globally.
Alternatively via npm:
```bash
npm install -g homectl
```
## Quick start
```bash
homectl init # interactive setup
homectl host ls # list all hosts
homectl context use prod # switch context
homectl service ls # list all services
homectl stack deploy myapp # deploy a compose stack
```
## Features
- **Unified host management** — one config to rule all your machines
- **SSH-first remote execution** — never expose your Docker daemon over TCP
- **Docker & Compose aware** — works with plain containers and full Compose stacks
- **Operation contexts** — switch between `lab`, `prod`, `staging` environments
- **Interactive init wizard** — TUI-based setup with keyboard navigation
- **Diagnostics engine** — deep health checks with actionable next steps
- **Cross-platform** — Windows, Linux, macOS
- **Machine-readable output** — `--json`, `--plain`, `--verbose`, `--quiet`
- **Safety-first** — `--dry-run`, confirmation prompts, input validation
- **Shell completion** — bash, zsh, fish
## Configuration
homectl uses a single YAML config file (default: `~/.config/homectl/config.yaml`):
```yaml
version: 1
defaultContext: lab
contexts:
- name: lab
host: media-node
hosts:
- name: local
connection:
type: local
host: localhost
runtime:
docker: true
compose: true
tags: [local, dev]
- name: vps-1
connection:
type: ssh
host: 203.0.113.10
user: deploy
port: 2222
identityFile: ~/.ssh/vps_deploy
runtime:
docker: true
compose: false
tags: [cloud, prod]
```
## Command reference
| Command | Description |
|---------|-------------|
| `init` | Interactive setup wizard |
| `host ls` | List all hosts |
| `host info ` | Show host details |
| `host ping ` | Check host connectivity |
| `host exec ` | Run command on host |
| `service ls` | List all services |
| `service info ` | Show service details |
| `service restart ` | Restart a service |
| `service start ` | Start a service |
| `service stop ` | Stop a service |
| `service pull ` | Pull latest image |
| `service health ` | Check service health |
| `logs tail ` | Tail service logs |
| `logs show ` | Show service logs |
| `context ls` | List contexts |
| `context show [name]` | Show context details |
| `context use ` | Switch context |
| `stack ls` | List Compose stacks |
| `stack info ` | Show stack details |
| `stack deploy ` | Deploy a stack |
| `stack down ` | Bring down a stack |
| `stack validate ` | Validate compose config |
| `doctor host [name]` | Check host health |
| `doctor config` | Validate configuration |
| `doctor all` | Full diagnostics |
| `doctor run [host]` | Full diagnostics suite |
| `backup run ` | Run a backup |
| `backup ls` | List backups |
| `backup verify ` | Verify latest backup |
| `config validate` | Validate config file |
| `config show` | Show current config |
| `cloud ls` | List cloud instances |
| `cloud providers` | List cloud providers |
| `auth check` | Check SSH authentication |
| `completion [shell]` | Generate shell completions |
## License
MIT