GitHub – Blackmamoth/sshsync

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:

1. 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.
2. Throughout this documentation, whenever “host” is mentioned, it refers to the SSH alias defined by the Host directive in your ~/.ssh/config file, not the actual hostname (HostName directive). 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

Clone 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] CMD

Options:

• --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 CMD

Options:

• --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_PATH

Options:

• --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_PATH

Options:

• --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] GROUP

Arguments:

• GROUP – The group to add hosts to (required)

Example:

# Add hosts to the 'web' group
sshsync gadd web

This command interactively adds a new host to your SSH config file.

Example:

# Add a new host to your SSH configuration
sshsync hadd

This command prompts for group assignments for all ungrouped hosts and updates the config.

Example:

# Assign groups to all ungrouped hosts
sshsync sync

Options:

• --with-status – Show whether a host is reachable

Example:

# List all hosts with their connection status
sshsync ls --with-status

sshsync stores its configuration in a YAML file located at ~/.config/sshsync/config.yaml. It uses your existing SSH configuration from ~/.ssh/config for host connection details and stores only group information in its own config file. Before running other commands, it’s recommended to run sshsync sync to assign hosts to groups for easier targeting.

Note about hosts: sshsync uses the SSH alias (the Host directive) from your ~/.ssh/config file, 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.com

You 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

Keep your files stored safely and securely with the SanDisk 2TB Extreme Portable SSD. With over 69,505 ratings and an impressive 4.6 out of 5 stars, this product has been purchased over 8K+ times in the past month. At only $129.99, this Amazon’s Choice product is a must-have for secure file storage.

Help keep private content private with the included password protection featuring 256-bit AES hardware encryption. Order now for just $129.99 on Amazon!

Help Power Techcratic’s Future – Scan To Support

If Techcratic’s content and insights have helped you, consider giving back by supporting the platform with crypto. Every contribution makes a difference, whether it’s for high-quality content, server maintenance, or future updates. Techcratic is constantly evolving, and your support helps drive that progress.

As a solo operator who wears all the hats, creating content, managing the tech, and running the site, your support allows me to stay focused on delivering valuable resources. Your support keeps everything running smoothly and enables me to continue creating the content you love. I’m deeply grateful for your support, it truly means the world to me! Thank you!