domus-cli - Infrastructure Orchestration CLI

Overview

domus-cli is an SSH-based infrastructure orchestration tool that complements netapi. While netapi handles API-based interactions with network devices (pfSense, ISE, WLC, Synology), domus-cli handles SSH-based operations across Linux infrastructure.

Tool Backend Purpose

netapi

REST APIs

Network device management (pfSense, ISE, WLC, Synology)

domus-cli

SSH

Linux infrastructure orchestration (KVM, k3s, Vault, BIND)

Repository

Architecture

domus-cli/
├── src/domus_cli/
│   ├── main.py              # Typer CLI entry point
│   ├── core/
│   │   ├── ssh.py           # SSH executor (paramiko/fabric)
│   │   ├── inventory.py     # Host inventory management
│   │   └── output.py        # Rich table formatters
│   └── commands/
│       ├── kvm.py           # virsh operations
│       ├── k3s.py           # kubectl operations
│       ├── vault.py         # vault CLI operations
│       └── network.py       # ip/bridge/vlan operations
├── pyproject.toml
└── README.md

Command Structure

# KVM operations
domus kvm vms list                     # All VMs across KVM hosts
domus kvm vms --host kvm-01            # Filter by host
domus kvm bridges                      # List all bridges
domus kvm interfaces kvm-01            # Network interfaces on host

# Network operations
domus network vlans                    # VLANs across infrastructure
domus network discovery                # Full topology discovery
domus network interfaces <host>        # Interface details

# k3s operations
domus k3s nodes                        # Node status across clusters
domus k3s pods -n monitoring           # Pods in namespace

# Inventory
domus inventory                        # Full infrastructure inventory
domus inventory --format json          # JSON output for automation

# Cross-system correlation
domus where vm ise-01                  # Which KVM host runs this VM?
domus where ip 10.50.1.120             # What system has this IP?

Core Components

SSH Executor

Handles SSH connections with:

  • Vault SSH CA certificate authentication

  • Connection pooling for multiple commands

  • Timeout and retry logic

  • Output capture and parsing

Host Inventory

Sources:

  • gopass: v3/domains/d000/infrastructure/hosts

  • Config file: ~/.config/domus-cli/hosts.yaml

  • DNS discovery: Query BIND for host records

Output Formatters

  • Rich tables (default)

  • JSON (--format json)

  • YAML (--format yaml)

  • CSV (--format csv)

Integration with netapi

domus-cli can call netapi internally for network device queries:

# In domus-cli commands
from netapi.vendors.pfsense import PfSenseClient

def get_vlans():
    # SSH to KVM for bridges
    bridges = ssh.run("kvm-01", "ip link show type bridge")

    # API to pfSense for VLANs
    pfsense = PfSenseClient()
    vlans = pfsense.get_interfaces()

    # Correlate and return unified view
    return merge(bridges, vlans)

Technology Stack

  • CLI Framework: Typer + Rich (same as netapi)

  • SSH: Paramiko or Fabric

  • Config: dynaconf or python-dotenv

  • Output: Rich tables, JSON

Roadmap

Phase 1: Foundation

  • Project scaffold (pyproject.toml, CLI structure)

  • SSH executor class with Vault cert support

  • Basic host inventory

  • domus kvm vms list command

Phase 2: KVM Operations

  • domus kvm bridges

  • domus kvm interfaces

  • domus kvm networks (libvirt)

  • VM start/stop/restart

Phase 3: Network Discovery

  • domus network vlans (correlate pfSense + KVM)

  • domus network discovery

  • Topology diagram generation (D2 output)

Phase 4: k3s Integration

  • domus k3s nodes

  • domus k3s pods

  • domus k3s services

Phase 5: Cross-System Queries

  • domus inventory

  • domus where commands

  • Search across all systems

Related