KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

ssh_commander

★ 127 Open GitHub ↗

Run sequential command(s) on a group of SSH servers

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# SSH Commander

SSH Commander is a powerful, colorful command-line tool for executing commands across multiple SSH servers simultaneously. It supports both password and key-based authentication, custom ports, and can execute both single commands and command files.

![SSH Commander Demo](https://raw.githubusercontent.com/AthenaNetworks/ssh_commander/main/docs/ssh-commander.gif)

## Features

- 🔑 Supports both password and key-based authentication
- 🌈 Colorized output for better readability
- 📁 Execute commands from files
- 🔄 Interactive server management
- 🔒 Secure password handling (never shown in terminal)
- 🚀 Single binary deployment
- ⚙️ YAML-based configuration
- 📊 Real-time output streaming
- ⌨️ Graceful interrupt handling (Ctrl+C support)

## System Requirements

### Linux
Ubuntu/Debian:
- Modern systems: `libffi8` and `libssl3`
- Older systems: `libffi7` and `libssl1.1`

CentOS/RHEL:
- Modern systems: `libffi-8` and `openssl-3`
- Older systems: `libffi-7` and `openssl-1.1`

### Windows
- Microsoft Visual C++ Redistributable

### macOS
- No additional requirements

## Installation

### Option 1: Debian Package (Ubuntu/Debian)

1. Download the latest .deb package from the [releases page](https://github.com/AthenaNetworks/ssh_commander/releases)
2. Install using dpkg:
```bash
sudo dpkg -i ssh-commander_*.deb
```

If you encounter any dependency errors during installation, run:
```bash
sudo apt -f install
```
This will automatically install any missing dependencies and complete the installation.

### Option 2: Using Pre-built Binaries

1. Download the latest release for your platform from the [releases page](https://github.com/AthenaNetworks/ssh_commander/releases)
2. Extract the archive
3. Run the installation script:
```bash
./install.sh  # For macOS/Linux
.\install.ps1  # For Windows (Run as Administrator)
```

### Option 3: Building from Source

1. Clone the repository:
```bash
git clone https://github.com/AthenaNetworks/ssh_commander.git
cd ssh_commander
```

2. Create a virtual environment and install dependencies:
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

3. Build the executable:
```bash
./build_all.sh
```

## Configuration

SSH Commander stores server configurations in `~/.config/ssh-commander/servers.yaml`. This file is automatically created when you add your first server.

### Configuration Format

The configuration file uses YAML format and supports both key-based and password authentication:

```yaml
# Key-based authentication (recommended)
- hostname: web1.example.com
  username: admin
  key_file: ~/.ssh/id_rsa  # Path to your SSH key
  port: 22  # Optional, defaults to 22
  tags: [prod, web]  # Optional, defaults to ['default']

# Password authentication
- hostname: db1.example.com
  username: dbadmin
  password: your_secure_password  # Not recommended for production use
  port: 2222
  tags: [prod, db]  # Optional server tags
```

### Security Notes

⚠️ **Important Security Warning**:
  - Passwords are stored in plaintext and are NOT secure
  - Anyone with access to your config file can see the passwords
  - This includes backup systems, cloud sync, etc.

✅ **Recommended Approach**:
- Use key-based authentication instead
  - Generate an SSH key: `ssh-keygen -t ed25519`
  - Copy to server: `ssh-copy-id user@hostname`
  - Use `key_file: ~/.ssh/id_ed25519` in config

### Configuration Security
- Config file is searched for in the following order:
  1. Path specified by `--config` argument
  2. `servers.yaml` in the same directory as the executable
  3. `~/.config/ssh-commander/servers.yaml`
- File permissions are set to user-only read/write (600)
- SSH key paths support `~` expansion to your home directory

## Usage

### Managing Servers

1. Add a new server interactively:
```bash
ssh-commander add
```

2. Add a server non-interactively (great for scripts/automation):
```bash
ssh-commander add -y \
    --hostname web1.example.com \
    --username admin \
    --key-file ~/.ssh/id_ed25519 \
    --tags prod,web
```

3. Edit an existing server in place:
```bash
ssh-commander edit web1.example.com --port 2222 --tags prod,web,frontend
ssh-commander edit web1.example.com --rename web1-new.example.com
ssh-commander edit db1.example.com --key-file ~/.ssh/id_ed25519
```

4. List configured servers (with optional filter and machine-readable output):
```bash
ssh-commander list                       # pretty
ssh-commander list -t prod -o hosts      # one hostname per line
ssh-commander list -o json               # JSON dump for jq/scripting
```

5. Remove one or more servers (prompts for confirmation):
```bash
ssh-commander remove web1.example.com web2.example.com
ssh-commander remove old-host.example.com --yes  # no prompt
```

6. Test SSH connectivity to all (or a subset of) servers:
```bash
ssh-commander test
ssh-commander test -t prod --parallel 8
```

7. Show the resolved config file path:
```bash
ssh-commander config-path
```

### Executing Commands

1. Run a single command on all servers:
```bash
ssh-commander exec -c "uptime"
```

2. Run a command on servers with specific tags:
```bash
ssh-commander exec -c "uptime" -t prod,web
```

3. Run a command across many servers in parallel:
```bash
ssh-commander exec -c "uptime" --parallel 8
```

4. Run multiple commands from a file:
```bash
ssh-commander exec -f commands.txt
```

5. Run commands from file on specific tags, stopping on the first failure:
```bash
ssh-commander exec -f commands.txt -t staging --stop-on-error
```

Example `commands.txt`:
```bash
# This is a comment - it will be skipped.
uptime
df -h
free -m
who
```

6. Use a different config file:
```bash
ssh-commander --config prod-servers.yaml exec -c "docker ps"
```

### Global Flags

All commands accept the following global options:

| Flag | Description |
| --- | --- |
| `--config FILE` | Override the config file path. |
| `--timeout SECONDS` | SSH connect/banner/auth timeout (default `10`). |
| `--no-color` | Disable ANSI color output (also respects piped output where possible). |
| `-q`, `--quiet` | Suppress informational output (errors still print). |
| `-v`, `--verbose` | Print extra diagnostic detail (incl. tracebacks on failure). |
| `--strict-host-key-checking` | Reject unknown SSH host keys instead of auto-adding them. |

### Exit Codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | User error (bad flags, missing config, etc.). |
| `2` | Invalid CLI argument. |
| `3` | One or more servers exited non-zero / failed connectivity. |
| `4` | DNS / network error. |
| `130` | Interrupted (Ctrl+C). |

### Real-world Examples

1. Check system status across all servers:
```bash
ssh-commander exec -c "systemctl status nginx"
```

2. Deploy updates:
```bash
ssh-commander exec -c "sudo apt update && sudo apt upgrade -y"
```

3. Monitor disk space:
```bash
ssh-commander exec -c "df -h / /var /home"
```

4. Check running Docker containers:
```bash
ssh-commander exec -c "docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
```

5. Execute a maintenance script:
```bash
# maintenance.txt
systemctl status nginx
df -h
free -m
find /var/log -type f -size +100M -exec ls -lh {} \;

# Run maintenance checks
ssh-commander exec -f maintenance.txt
```

## Output Formatting

SSH Commander uses colors to make output more readable:
- 🔵 Server names are highlighted in blue
- 🟢 Successful output is shown in green
- 🔴 Errors are displayed in red
- 🟣 Command execution status in purple

## Security Considerations

1. Password Storage:
   - Passwords in the config file should be treated with care
   - Consider using key-based authentication when possible
   - Use appropriate file permissions for your config file: `chmod 600 servers.yaml`

2. SSH Keys:
   - Key files should have proper permissions: `chmod 600 ~/.ssh/id_rsa`
   - Consider using different keys for different server groups

3. Network Security:
   - Be mindful of firewalls and network policies
   - Use custom ports if needed
   - Consider using jump hosts for isolated networks

## Contributing

1. Fork the repository
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

## License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0) - see the [LICENSE](LICENSE) file for details.

Key points of the GPL-3.0 license:
- ✅ You can use this software for commercial purposes
- ✅ You can modify the source code
- ✅ You can distribute your modifications
- ⚠️ You must disclose the source code of your modifications
- ⚠️ You must license your modifications under the GPL-3.0
- ⚠️ You must state the significant changes you made

## Support

If you encounter any issues or have questions:
1. Check the [Issues](https://github.com/AthenaNetworks/ssh_commander/issues) page
2. Create a new issue with detailed information about your problem
3. Include your OS version and Python version when reporting bugs

ssh_commander

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README