sshctl/man/sshctl.1

.TH SSHCTL 1 "2026-09-12" "sshctl v0.1.1" "SSH Configuration Management"
.SH NAME
sshctl \- SSH configuration management toolkit
.SH SYNOPSIS
.B sshctl
[\fIoptions\fR] \fIcommand\fR [\fIargs\fR]
.SH DESCRIPTION
sshctl is a CLI toolkit for managing SSH configurations, including host definitions,
proxy jumps, permissions, connectivity checks, and shell completions.
.SH OPTIONS
.TP
.B \-V, \-\-version
Show version.
.TP
.B \-v, \-\-verbose
Verbose output.
.TP
.B \-c, \-\-config \fIPATH\fR
Path to ssh_config file (default: ~/.ssh/config).
.TP
.B \-\-install-completion
Install shell completion for the current shell.
.TP
.B \-\-show-completion
Show shell completion script.
.TP
.B \-\-help
Show help message.
.SH COMMANDS
.SS Core
.TP
.B init
Initialize an SSH config directory structure.
.TP
.B validate
Validate SSH config structure and option correctness.
.TP
.B diff
Show differences between generated and current SSH config.
.TP
.B tree
Show the conf.d directory tree with host counts.
.TP
.B backup
Create a timestamped backup of the SSH config directory.
.TP
.B restore \fIPATH\fR
Restore SSH config from a backup.
.TP
.B cleanup [\-n]
Remove stale SSH control master sockets. Use \-n for dry-run.
.TP
.B log [\-n \fICOUNT\fR] [\-f]
Show recent sshctl activity log. Use \-f to follow (tail mode).
.TP
.B check [\-p \fIPATTERN\fR] [\-t \fISECS\fR] [\-c \fIMAX\fR]
Check connectivity to all hosts in parallel.
.TP
.B exec \fICOMMAND\fR [\-p \fIPATTERN\fR] [\-t \fISECS\fR]
Run a command in parallel across hosts.
.TP
.B csv [\-o \fIFILE\fR]
Export host inventory to CSV.
.TP
.B ansible [\-o \fIFILE\fR] [\-\-group-by \fIFIELD\fR]
Generate Ansible inventory from SSH config.
.TP
.B chmod [\-\-fix]
Check (and optionally fix) SSH directory permissions.
.SS Config Management
.TP
.B config show
Show all global Host * options.
.TP
.B config set \fIKEY\fR \fIVALUE\fR
Set an option in the Host * block.
.TP
.B config unset \fIKEY\fR
Remove an option from the Host * block.
.SS Host Management
.TP
.B host list
List all host aliases with HostName and ProxyJump.
.TP
.B host show \fIALIAS\fR
Show options for a specific host.
.TP
.B host add \fIALIAS\fR \fIHOSTNAME\fR [\-u \fIUSER\fR] [\-p \fIPORT\fR] [\-j \fIJUMP\fR]
Add a new host alias.
.TP
.B host edit \fIALIAS\fR \-\-option \fIOPT\fR \-\-value \fIVAL\fR
Set an option on an existing host.
.TP
.B host remove \fIALIAS\fR [\-f]
Remove a host from its config file (with confirmation).
.SS ProxyJump
.TP
.B jump on
Restore all saved ProxyJump directives.
.TP
.B jump off
Save and remove all ProxyJump lines from conf.d files.
.TP
.B jump status
List all hosts with ProxyJump and show saved state.
.TP
.B jump auto [\-\-subnet] [\-\-no-subnet]
Auto-detect network environment:
- Probes jump gateways via TCP (respects HostName/Port from SSH config)
- Falls back to SSID matching against known internal networks
- Enables or disables ProxyJump accordingly.
.TP
.B jump networks [list|add|remove] [\-\-ssid \fIPATTERN\fR]
Manage internal SSID patterns for auto-detection (defaults: MobinNet*, Mobin*).
.SS Setup
.TP
.B setup completions [\-\-shell \fIbash|zsh|fish\fR]
Install shell completions.
.TP
.B setup agent [start|stop|restart|status]
Manage the ssh-agent systemd user service.
.TP
.B setup timer [cleanup|check] [\-a enable|disable|status]
Manage systemd timers.
.TP
.B setup git
Initialize git tracking in ~/.ssh.
.TP
.B setup init
Full setup: git + agent + timers + completions.
.SS Diagnostics
.TP
.B heal [\-\-dry-run]
Detect and fix config issues (typos, invalid options).
.SH FILES
.TP
.I ~/.ssh/config
Main SSH configuration file.
.TP
.I ~/.ssh/conf.d/
Directory containing host definition files.
.TP
.I ~/.ssh/control.d/
SSH control master socket directory.
.TP
.I ~/.ssh/keys.d/
SSH key files.
.TP
.I ~/.ssh/scripts/
Helper scripts and systemd unit files.
.TP
.I ~/.ssh/report/events.ndjson
Activity event log (NDJSON format).
.TP
.I ~/.ssh/.proxyjump_save
Saved ProxyJump state (temporary, created by \fBjump off\fR).
.TP
.I ~/.ssh/.internal_ssids
Internal SSID patterns for auto-detect.
.SH ENVIRONMENT
.TP
.B SSH_AUTH_SOCK
SSH agent socket path. Set to \fI$XDG_RUNTIME_DIR/ssh-agent.socket\fR when using
the built-in systemd ssh-agent service.
.SH EXAMPLES
.TP
Initialize a new SSH config directory:
    sshctl init
.TP
List all hosts:
    sshctl host list
.TP
Show host details:
    sshctl host show myserver
.TP
Disable all ProxyJump directives (internal network):
    sshctl jump off
.TP
Auto-detect network and toggle ProxyJump:
    sshctl jump auto
.TP
Add current Wi-Fi as internal network:
    sshctl jump networks add
.TP
Check all hosts connectivity:
    sshctl check
.TP
View activity log:
    sshctl log \-n 20
.TP
Validate and fix config issues:
    sshctl heal
.SH BUGS
Report issues at https://git.panahifar.ir/ahp/sshctl/issues
.SH AUTHOR
Amir Husayn Panahifar
.SH SEE ALSO
.BR ssh (1),
.BR ssh_config (5),
.BR sshd (8)