sshsync is a fast, minimal CLI tool to run shell commands across multiple remote servers via SSH. Easily target all servers or just a specific group, great for sysadmins, developers, and automation workflows.
IMPORTANT:
- sshsync uses asyncssh for SSH connections. If you use passphrase-protected SSH keys, you MUST have your ssh-agent running with the keys added via ssh-add. sshsync will rely on SSH agent forwarding to authenticate with protected keys.
- Throughout this documentation, whenever "host" is mentioned, it refers to the SSH alias defined by the
Hostdirective in your~/.ssh/configfile, not the actual hostname (HostNamedirective). sshsync uses these aliases for all operations.
- 🔁 Run shell commands on all hosts or specific groups
- 🚀 Executes commands concurrently across servers
- 🧠 Group-based configuration for easy targeting
- 🕒 Adjustable SSH timeout settings
- 📁 Push/pull files between local and remote hosts
- 📊 Operation history and logging
- 🔍 Dry-run mode to preview actions before execution
- Python 3.10 or higher
pip install sshsyncClone and install manually:
git clone https://github.com/Blackmamoth/sshsync.git
cd sshsync
pipx install .sshsync [OPTIONS] COMMAND [ARGS]...Global Options:
--install-completion- Install completion for the current shell--show-completion- Show completion for the current shell--help- Show help message and exit
sshsync [OPTIONS] COMMAND [ARGS]...sshsync all [OPTIONS] CMDOptions:
--timeout INTEGER- Timeout in seconds for SSH command execution (default: 10)--dry-run- Show command and host info without executing
Examples:
# Check disk space on all servers with a 20 second timeout
sshsync all --timeout 20 "df -h"
# Preview which hosts would receive the command without executing
sshsync all --dry-run "systemctl restart nginx"sshsync group [OPTIONS] NAME CMDOptions:
--timeout INTEGER- Timeout in seconds for SSH command execution (default: 10)--dry-run- Show command and host info without executing
Examples:
# Restart web services on production servers
sshsync group web-servers "sudo systemctl restart nginx"
# Preview the command execution on database servers without executing
sshsync group db-servers --dry-run "service postgresql restart"sshsync push [OPTIONS] LOCAL_PATH REMOTE_PATHOptions:
--all- Push to all configured hosts--group TEXT- Push to a specific group of hosts--host TEXT- Push to a single specific host--recurse- Recursively push a directory and its contents--dry-run- Show transfer and host info without executing
Examples:
# Push configuration file to all hosts
sshsync push --all ./config.yml /etc/app/config.yml
# Push directory to web-servers group recursively
sshsync push --group web-servers --recurse ./app/ /var/www/app/
# Preview file transfer to a specific host without executing
sshsync push --host staging-db --dry-run ./db-config.json /etc/postgres/conf.d/sshsync pull [OPTIONS] REMOTE_PATH LOCAL_PATHOptions:
--all- Pull from all configured hosts--group TEXT- Pull from a specific group of hosts--host TEXT- Pull from a single specific host--recurse- Recursively pull a directory and its contents--dry-run- Show transfer and host info without executing
Examples:
# Pull log files from all database servers
sshsync pull --group db-servers /var/log/mysql/error.log ./logs/
# Pull configuration directory from a specific host
sshsync pull --host prod-web-01 --recurse /etc/nginx/ ./backups/nginx-configs/
# Preview which files would be pulled without executing
sshsync pull --group web-servers --dry-run /var/log/nginx/access.log ./logs/sshsync gadd [OPTIONS] GROUPArguments:
GROUP- The group to add hosts to (required)
Example:
# Add hosts to the 'web' group
sshsync gadd websshsync hadd [OPTIONS]This command interactively adds a new host to your SSH config file.
Example:
# Add a new host to your SSH configuration
sshsync haddsshsync sync [OPTIONS]This command prompts for group assignments for all ungrouped hosts and updates the config.
Example:
# Assign groups to all ungrouped hosts
sshsync syncsshsync ls [OPTIONS]Options:
--with-status- Show whether a host is reachable
Example:
# List all hosts with their connection status
sshsync ls --with-statussshsync versionsshsync stores its configuration in a YAML file located at
~/.config/sshsync/config.yaml. It uses your existing SSH configuration from~/.ssh/configfor host connection details and stores only group information in its own config file. Before running other commands, it's recommended to runsshsync syncto assign hosts to groups for easier targeting.Note about hosts: sshsync uses the SSH alias (the
Hostdirective) from your~/.ssh/configfile, not the actual hostname. This means when you specify a host in any sshsync command, you're referring to the SSH alias that you've defined in your SSH config.
groups:
dev:
- example.site
work:
- work.dev
- ssh.work.dev
web:
- cloudmesh
- example.comYou can edit this file manually or use the built-in commands to manage groups and hosts.
Note: sshsync leverages your existing SSH configuration for host details, making it easier to maintain a single source of truth for SSH connections.
sshsync now includes operation history and logging functionality. Logs are stored in platform-specific locations:
- Windows:
%LOCALAPPDATA%\sshsync\logs - macOS:
~/Library/Logs/sshsync - Linux:
~/.local/state/sshsync
These logs track command executions, file transfers, and any errors that occur during operations.
# Check disk space on all servers
sshsync all "df -h"
# View memory usage on all database servers with increased timeout
sshsync group db-servers --timeout 30 "free -m"
# Preview a potentially destructive command without execution
sshsync all --dry-run "sudo apt update && sudo apt upgrade -y"
# Push configuration files to production servers recursively
sshsync push --group production --recurse ./configs/ /etc/app/configs/
# Pull log files from all web servers
sshsync pull --group web-servers /var/log/nginx/error.log ./logs/
# Preview file transfers to validate paths before execution
sshsync push --all --dry-run ./sensitive-config.json /etc/app/config.json
# Add hosts to the dev group
sshsync gadd dev
# Add a new host to your SSH configuration
sshsync hadd
# Assign groups to all ungrouped hosts
sshsync sync
# Check if hosts are reachable
sshsync ls --with-status- Live results display (--live flag) to show command outputs as they complete
- Performance optimizations for large server fleets
- Support for additional authentication methods
- Automated versioning using release-please for streamlined releases
MIT License