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.8.0 Release Highlights

v2.8.0 adds the first P3 user-facing features: connection profiles and machine-readable CLI output. Public APIs remain backward compatible; the default CLI output and all existing commands behave exactly as before. See the full migration notes.

Connection Profiles

• New HostProfile (exported from remote_cmd): reusable connection defaults — username, port, key file, tags, description — stored by both JSON and SQLite repositories via the optional ProfileStore capability (the HostRepository ABC is unchanged).
• Hosts reference a profile (host add --profile aws); values merge at connect time (reference model): port when the host uses the default 22, key file when unset, description when empty, tags as a union, username when the host stores none (live default — later profile username changes propagate).
• Changing a profile applies to every referencing host; unknown profiles fail with a clear ConfigError (batch execution reports them per host).
• ProfileService CRUD + remote-cmd profile add/list/show/remove, with deletion protection for profiles still referenced by hosts.

Machine-Readable Output

• remote-cmd run and remote-cmd batch-run accept --format rich|json|table (default rich = byte-compatible with previous output).
• JSON uses a stable schema with sorted result keys; table output is plain aligned text. Machine formats suppress the progress bar/header so stdout stays parseable.
• The formatter layer lives in remote_cmd/cli/formatters/ and never touches the execution kernels.

Try It

remote-cmd profile add aws -u ec2-user -k ~/.ssh/aws.pem -t cloud
remote-cmd host add web-01 10.0.0.10 --profile aws
remote-cmd batch-run web-01 web-02 "uptime" --format json | jq .

Table of Contents

• v2.8.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.10+ 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 ⭐}