Parse — Full SSH config parser supporting Host, Include, glob patterns, and continuation lines
Generate — Programmatic SSH config generation with deterministic option ordering
Validate — Validate SSH config structure, check required options and missing includes
Check — Parallel DNS/TCP/SSH connectivity checking across all hosts
Exec — Run commands concurrently across all hosts via SSH
Export — Export host inventory to CSV
Ansible — Generate Ansible inventory from your SSH config directory tree
Permissions — Fix or verify SSH directory permissions (0700 dirs, 0600 keys, 0644 public keys)
CLI — Full-featured typer CLI with rich output (tables, trees, status)

Installation

pip (wheel)

pip install sshctl # once published to PyPI
# or install the built wheel directly from a release
pip install ./sshctl-0.1.2-py3-none-any.whl

dpkg (Debian/Ubuntu)

# Download from latest release
wget https://src.panahifar.ir/ahp/sshctl/releases/download/v0.1.2/sshctl_0.1.2-1_all.deb
sudo dpkg -i sshctl_0.1.2-1_all.deb

From source

git clone https://src.panahifar.ir/ahp/sshctl.git
cd sshctl
pip install -e .

Download the latest .whl or .deb from the releases page.

Quick Start

# Initialize SSH config directory structure
sshctl init

# List all hosts
sshctl host list

# Show a specific host
sshctl host show server1

# Validate config
sshctl validate

# Check host connectivity
sshctl check

# Run a command across all hosts in parallel
sshctl exec "uptime"

# Export inventory as CSV
sshctl csv --output hosts.csv

# Generate Ansible inventory
sshctl ansible

# Fix SSH directory permissions
sshctl chmod

# Only check permissions (no fixes)
sshctl chmod --check

# Show conf.d directory tree
sshctl tree

Directory Structure

~/.ssh/
├── config              # Main SSH config (Include conf.d/)
├── conf.d/             # Modular host configurations
│   ├── internal/       # Internal infrastructure universe
│   │   ├── AZ/         # Sector (e.g., region)
│   │   │   └── cluster1/
│   │   │       └── 8xx-serverfarm/
│   │   │           └── 82-k8s/
│   │   │               └── hosts.conf
│   │   └── ...
│   └── external/       # External/dedicated universe
│       └── ...
├── control.d/          # SSH control master sockets
├── keys.d/             # Private keys (auto-protected by sshctl chmod)
├── keys.pub/           # Public keys
├── report/             # Generated reports
└── inventory.d/        # Generated Ansible inventory
    └── hosts.yml

ZonePath Convention

The conf.d/ hierarchy follows a ZonePath addressing model:

conf.d/{universe}/{sector}/{cluster}/{zone}/{vlan}

Level	Description	Example
universe	`internal` or `external`	`internal`
sector	Geographic/segment	`AZ`
cluster	Data center / DC	`cluster1`
zone	Server farm / role	`8xx-serverfarm`
vlan	Network segment	`82-k8s`

CLI Reference

Global Options

Flag	Description
`-V`, `--version`	Show version
`-v`, `--verbose`	Verbose logging
`-c`, `--config`	Path to SSH config file

Commands

Command	Description
`init`	Initialize SSH config directory structure
`host list`	List all host aliases
`host show`	Show details for a specific host
`host add`	Add a new host to the SSH config
`check`	Check connectivity to all hosts
`exec`	Run a command in parallel across hosts
`csv`	Export host inventory to CSV
`chmod`	Fix or check SSH directory permissions
`validate`	Validate SSH config structure
`diff`	Show differences between generated and current config
`backup`	Create timestamped backup of SSH config directory
`restore <path>`	Restore SSH config from a backup
`ansible`	Generate Ansible inventory from SSH config
`tree`	Show the conf.d directory tree
`install-completion`	Install shell completions (bash/zsh/fish)

Python API

from pathlib import Path
from sshctl.parser import parse_file, resolve_includes
from sshctl.models import HostBlock, SshConfig
from sshctl.generator import generate_config_text, write_config_file
from sshctl.validator import validate_config
from sshctl.resolver import resolve_host, resolve_all_hosts
from sshctl.exporter import export_csv
from sshctl.permissions import fix_ssh_permissions, check_permissions
from sshctl.inventory import generate_inventory

# Parse an SSH config
config = parse_file(Path("~/.ssh/config").expanduser())

# Resolve includes recursively
full_config = resolve_includes(Path("~/.ssh/config"))

# Find hosts
block = config.find("server1")
blocks = config.find_all("web*")

# Validate
result = validate_config(Path("~/.ssh/config"))
if not result.passed:
    for issue in result.issues:
        print(f"[{issue.severity}] {issue.message}")

# Resolve a host (uses ssh -G)
resolved = resolve_host("server1", Path("~/.ssh/config"))

# Generate config text
text = generate_config_text(full_config)

# Generate Ansible inventory
inventory = generate_inventory(Path("~/.ssh"))

# Fix permissions
counts = fix_ssh_permissions(Path("~/.ssh"))

Configuration

sshctl can be configured via YAML or environment variables.

YAML (`~/.ssh/sshctl.yaml`)

ssh_dir: ~/.ssh
config_file: config
verbose: false
timeout: 10

Environment Variables

All settings can be overridden with SSHCTL_ prefix:

export SSHCTL_VERBOSE=true
export SSHCTL_TIMEOUT=30

Development

Setup

git clone https://src.panahifar.ir/ahp/sshctl.git
cd sshctl
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run Tests

pytest

Lint & Type Check

ruff check src/ tests/
ruff format --check src/ tests/
mypy src/ tests/

Project Structure

sshctl/
├── src/
│   └── sshctl/
│       ├── __init__.py          # Package init, re-exports from core
│       ├── __main__.py          # Entry point for python -m sshctl
│       │
│       ├── cli/                 # CLI layer (user-facing)
│       │   ├── __init__.py
│       │   ├── app.py           # Typer CLI application
│       │   └── __main__.py      # Module entry point
│       │
│       ├── core/                # Core domain (shared foundation)
│       │   ├── __init__.py      # Exports __version__
│       │   ├── _version.py      # Version string
│       │   ├── config.py        # Pydantic settings (SshctlConfig)
│       │   ├── exceptions.py    # Exception hierarchy
│       │   ├── logutil.py       # Structured logging (structlog)
│       │   └── models.py        # Data models (HostBlock, SshConfig, ZonePath)
│       │
│       ├── config/              # SSH config lifecycle
│       │   ├── __init__.py
│       │   ├── parser.py        # SSH config parser + include resolution
│       │   ├── generator.py     # SSH config text generation
│       │   ├── resolver.py      # Host resolution via ssh -G
│       │   └── validator.py     # Config validation
│       │
│       ├── operations/          # Active operations
│       │   ├── __init__.py
│       │   ├── checker.py       # DNS/TCP/SSH connectivity checks
│       │   └── executor.py      # Parallel SSH command execution
│       │
│       └── export/              # Export/integration
│           ├── __init__.py
│           ├── exporter.py      # CSV export
│           ├── inventory.py     # Ansible inventory generation
│           └── permissions.py   # SSH directory permissions
│
├── tests/
│   ├── conftest.py              # Pytest fixtures
│   ├── test_config.py
│   ├── test_exceptions.py
│   ├── test_exporter.py
│   ├── test_generator.py
│   ├── test_inventory.py
│   ├── test_models.py
│   ├── test_parser.py
│   ├── test_permissions.py
│   └── test_validator.py
│
├── pyproject.toml               # Build config, ruff, mypy, pytest
├── .editorconfig
├── .gitignore
├── LICENSE
└── README.md

Architecture

sshctl follows a modular layered architecture organized into subpackages:

┌─────────────────────────────────────────────────────────────┐
│                    cli/ (app.py)                            │
│              Typer CLI, Rich output, orchestration          │
└──────────────────────┬──────────────────────────────────────┘
                       │
          ┌────────────┼────────────────┬────────────────┐
          ▼            ▼                ▼                ▼
   ┌──────────┐ ┌───────────┐ ┌──────────────┐ ┌──────────────┐
   │ config/  │ │operations │ │   export/    │ │    core/     │
   │          │ │           │ │              │ │              │
   │ parser   │ │ checker   │ │ exporter     │ │ models       │
   │ generator│ │ executor  │ │ inventory    │ │ exceptions   │
   │ resolver │ │           │ │ permissions  │ │ config       │
   │ validator│ │           │ │              │ │ logutil      │
   └──────────┘ └───────────┘ └──────────────┘ └──────────────┘
                                                    ▲
                                                    │
                                            (shared foundation)

Key design decisions:

Models first — HostBlock, SshConfig, ZonePath are plain dataclasses; the entire pipeline operates on them
Parser is lossy by design — it extracts enough structure for management, not a perfect SSH config round-trip
Resolver delegates to ssh -G — rather than reimplementing SSH's full inheritance logic, sshctl shells out for the canonical resolved view
Async everywhere — checker and executor use asyncio with semaphore-controlled concurrency

License

MIT — see LICENSE

README.md

sshctl

Features