Tested on Linux, macOS, and Windows

Remote CMD — SSH Server Management
Without the Overhead

·

pip install remote_cmd_manager  ·  Quick Start  ·  Use Cases  ·  CLI Reference  ·  Python API  ·  Documentation  ·  Contributing

Remote CMD is a lightweight Python CLI + API for managing servers over SSH. Add hosts, run commands, transfer files, and organize hosts with tags — no Ansible DSL or shell loops required.

# One command to get started
pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu --key ~/.ssh/id_rsa && remote-cmd run web-01 "uptime"

v2.4.0 Release Highlights

v2.4.0 adds an opt-in retained-output cap for batch execution and cleans up logging handler resources, with default behavior and public result schemas unchanged. See the full migration notes before upgrading automated callers.

Bounded Batch Output

• BatchExecutor / AsyncBatchExecutor accept an optional max_output_bytes (default None): None keeps full stdout/stderr, while a positive value caps each host's retained streams and appends a [output truncated: N bytes omitted] marker.
• Truncation is deterministic and UTF-8 byte-boundary safe, applies to stdout and stderr independently, and never changes command success/failure or exit codes.
• The cap bounds the retained BatchResult; the SSH client may still hold full output transiently during execution, so it is not a process-wide RSS limit.

Reliability

• setup_logging now closes previous root-logger handlers before removing them, avoiding unclosed-file resource warnings when logging is reconfigured.
• Connection-pool lifetime wording in the documentation now matches the actual behavior: internal pools are created lazily per host and closed as soon as that host finishes (including its retries).

Compatibility

• Default behavior is unchanged (max_output_bytes=None retains full output) and the public BatchResult / BatchHostResult schemas are unchanged.

Table of Contents

• v2.4.0 Release Highlights
• Why Remote CMD?
• Quick Start
• Use Cases
• CLI Reference
• Python API
• Features
• Installation
• Documentation
• Project Status
• Maintainership
• Contributing
• License

Why Remote CMD?

Use remote-cmd when you need a CLI that works immediately for ad-hoc SSH tasks. Use Ansible when you need full configuration management and idempotent playbooks.

Quick Start

# 1. Install
pip install remote_cmd_manager

# 2. Add a server
remote-cmd host add web-01 192.168.1.10 ubuntu --key ~/.ssh/id_rsa

# 3. Run a command
remote-cmd run web-01 "uptime"

# 4. Run across named production servers
remote-cmd batch-run web-01 web-02 db-01 "df -h /"

Use Cases

🖥️ System Administrators — Check disk across 20 servers in one command

remote-cmd batch-run web-01 web-02 db-01 "df -h / | tail -1"
# Output:
#   ✓ web-01  → /dev/sda1  32G  12G  19G  40% /
#   ✓ web-02  → /dev/sda1  32G  28G   3G  90% /   ⚠️
#   ✗ db-01   → Connection refused

🚀 Deploy — Pull code and restart a service

from remote_cmd.service.host_service import HostService
from remote_cmd.repository import JsonHostRepository

service = HostService(repository=JsonHostRepository("hosts.json"))
for host in service.list_hosts(tag="staging"):
    with service.connect_to_host(host.name) as client:
        client.execute("cd /app && git pull")
        client.execute("pip install -r requirements.txt")
        client.execute_sudo("systemctl restart app", password="sudopass")

🔥 Incident Response — Check logs across all servers

remote-cmd batch-run web-01 web-02 "journalctl -xe -n 50 | grep -i error"

🔧 Config Update — Upload and reload nginx across tagged hosts

# Upload new config, reload across web servers
remote-cmd run web-01 "sudo cp /tmp/nginx.conf /etc/nginx/nginx.conf && sudo nginx -t && sudo systemctl reload nginx"

CLI Reference

All operations are available from the terminal:

Python API

Use Remote CMD inside your own scripts and automation:

from remote_cmd.core.ssh_client import SSHClient, ConnectionConfig

config = ConnectionConfig(
    hostname="192.168.1.100",
    username="ubuntu",
    key_filename="~/.ssh/id_rsa",
)

with SSHClient(config) as client:
    # Execute commands
    result = client.execute("uptime")
    print(result.stdout)

    # Transfer files
    client.upload_file("./local.txt", "/remote/path/file.txt")
    client.download_file("/remote/path/file.txt", "./local.txt")

    # List remote directory
    for entry in client.list_remote_directory("/var/log"):
        print(f"{entry.name}: {entry.size} bytes")

Features

Cross-Platform Support

remote-cmd is a pure-Python client, tested and supported on Linux, macOS, and Windows. No native dependencies or platform-specific builds are required.

Note on Windows file permissions: Credential encryption keys are protected with 0600 permissions on Unix. On Windows this restriction is not enforced by the filesystem — the key file is still encrypted at rest. For production Windows use, consider adding filesystem-level ACLs.

Installation

# From PyPI (recommended) — keeps API and CLI in sync
pip install remote_cmd_manager

# With native async support (AsyncSSHClient / AsyncConnectionPool / AsyncBatchExecutor)
pip install "remote_cmd_manager[async]"

# From source
git clone git@github.com:Vae-Scrooge/remote-cmd.git
cd remote-cmd
pip install -e ".[dev]"

The [async] extra installs asyncssh and enables the native async execution kernel: AsyncSSHClient, AsyncConnectionPool and AsyncBatchExecutor (also available via BatchExecutor(use_async=True)). BatchExecutor(use_async=True) also requires this extra. Without it, import remote_cmd still works — the async symbols are simply not exported.

Documentation

📚 Full Documentation Center — tutorials, API reference, architecture, and troubleshooting

Note: The documentation center and tutorials are maintained in English. See README.zh-CN.md for the Chinese version of this page.

Project Status

Stable. The core API is stable and versioned under semantic versioning. Breaking changes are communicated via major-version bumps, and the public API surface has been stable since the 1.x line.

Roadmap:

• Async SSH operations (parallel execution) — v1.1.0
• Pluggable storage backends (JSON + SQLite) — v1.2.x
• Chainable credential providers + at-rest encryption — v1.2.x
• Configuration profiles (AWS, GCP, custom)
• Output formatting (JSON, table)
• Templated command recipes

Good first issues are labelled good first issue in the issue tracker — contributions welcome.

Maintainership

Remote CMD is an actively maintained open-source project. It is designed and developed independently as a focused alternative to heavyweight tools for the ad-hoc SSH tasks that come up in day-to-day server work.

• Project health: CI runs on every PR, Python 3.9+ is supported, and the public API is versioned under semantic versioning.
• Your code, your servers: usage stays open under the MIT license — nothing is telemetry-driven or locked behind a service.
• Why open source? The tooling around ad-hoc SSH administration was either too heavy (Ansible) or too bare (raw shell loops). Remote CMD exists so that a single command can cover the common 90% of remote admin.

Contributing

We welcome contributions! See CONTRIBUTING.md to get started.

Before contributing, please read our Code of Conduct.

License

MIT © Vae-Scrooge

_{If you find this project useful, star it on GitHub ⭐}