Module API Tutorial (EN)

Start with SSHScript as a regular Python module. The Dollar syntax is an optional concise notation for .spy files.

Create a Session

import sshscript

session = sshscript.Session()
try:
    stdout, stderr = session.exec_command("hostname")
    print(str(stdout).strip())
finally:
    session.close()

The latest command result is available as session.stdout, session.stderr, and session.exitcode.

Execute local commands

exec_command() accepts a string command. It automatically uses a shell when the string contains a pipeline, redirect, expansion, or logical operator.

command = "python3 -c \"print('ready')\""
stdout, stderr = session.exec_command(command, shell=False)
stdout, stderr = session.exec_command("printf 'alpha\\nbeta\\n' | grep beta")

Use shell=False or shell=True to override automatic selection.

Connect and compose contexts

with session.connect("ops@example.net") as remote:
    remote.exec_command("hostname")

    with remote.sudo(password="obtained securely") as root:
        root.exec_command("systemctl restart nginx")

Connections can be nested for bastion hosts. The returned session is the object that runs commands, transfers files, and opens interactive programs.

Interactive programs and files

with session.connect("ops@example.net") as remote:
    with remote.enter("python3", prompt=">>>", exit="quit()") as console:
        console.input("print('hello')")
        console.expect("hello")

    remote.upload("./release.tar.gz", "/var/tmp/", makedirs=True)
    remote.download("/var/tmp/report.txt", "./reports/")

Optional Dollar syntax

For a standalone .spy automation file, the same model can be written more concisely:

with $.connect("ops@example.net"):
    $systemctl restart nginx

Run it with python3 sshscript.py maintenance.spy. See Dollar Syntax Add-on only when this notation suits the team.

Last Updated: 2026-07-26 16:53:25