SSH

Remote server command execution and file management via SSH and SFTP

Package: @robinpath/ssh | Category: Web | Type: Utility

Authentication

ssh.connect "server" {"host": "example.com", "username": "admin", "password": "..."}

Call this once at the start of your script before using any other function. Credentials persist for the duration of the script execution.

Use Cases

Use the ssh module when you need to:

• Execute a command on the remote server -- Use ssh.exec to perform this operation
• Upload a local file to the remote server via SFTP -- Use ssh.upload to perform this operation
• Download a remote file to local filesystem via SFTP -- Use ssh.download to perform this operation
• Create a directory on the remote server -- Use ssh.mkdir to perform this operation
• List files in a remote directory -- Use ssh.ls to perform this operation

Quick Reference

Function	Description	Returns
connect	Connect to an SSH server	Connection id
exec	Execute a command on the remote server	{stdout, stderr, code}
upload	Upload a local file to the remote server via SFTP	{uploaded}
download	Download a remote file to local filesystem via SFTP	{downloaded}
mkdir	Create a directory on the remote server	True on success
ls	List files in a remote directory	Array of {name, size, modifyTime, isDirectory}
rm	Remove a file on the remote server	True on success
rmdir	Remove a directory on the remote server	True on success
stat	Get file or directory stats from the remote server	{size, modifyTime, accessTime, isDirectory, isFile}
readFile	Read the contents of a remote file as a string	File content as UTF-8 string
writeFile	Write string content to a remote file	True on success
close	Close an SSH connection	True if closed, false if not found
isConnected	Check if an SSH connection is alive	True if connected

Functions

connect

Connect to an SSH server

Module: ssh | Returns: string -- Connection id

ssh.connect "server" {"host": "example.com", "username": "admin", "password": "..."}

Parameter	Type	Required	Description
id	string	Yes	Connection identifier
options	object	Yes	{host, port, username, password, privateKey, privateKeyPath, passphrase}

---

exec

Execute a command on the remote server

Module: ssh | Returns: object -- {stdout, stderr, code}

ssh.exec "server" "ls -la /var/log"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
command	string	Yes	Shell command to execute

---

upload

Upload a local file to the remote server via SFTP

Module: ssh | Returns: object -- {uploaded}

ssh.upload "server" "./deploy.tar.gz" "/opt/app/deploy.tar.gz"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
localPath	string	Yes	Local file path
remotePath	string	Yes	Remote destination path

---

download

Download a remote file to local filesystem via SFTP

Module: ssh | Returns: object -- {downloaded}

ssh.download "server" "/var/log/app.log" "./app.log"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
remotePath	string	Yes	Remote file path
localPath	string	Yes	Local destination path

---

mkdir

Create a directory on the remote server

Module: ssh | Returns: boolean -- True on success

ssh.mkdir "server" "/opt/app/logs"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
remotePath	string	Yes	Remote directory path

---

ls

List files in a remote directory

Module: ssh | Returns: array -- Array of {name, size, modifyTime, isDirectory}

ssh.ls "server" "/var/log"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
remotePath	string	No	Remote directory path (default /)

---

rm

Remove a file on the remote server

Module: ssh | Returns: boolean -- True on success

ssh.rm "server" "/tmp/old-file.txt"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
remotePath	string	Yes	Remote file path

---

rmdir

Remove a directory on the remote server

Module: ssh | Returns: boolean -- True on success

ssh.rmdir "server" "/tmp/old-dir"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
remotePath	string	Yes	Remote directory path

---

stat

Get file or directory stats from the remote server

Module: ssh | Returns: object -- {size, modifyTime, accessTime, isDirectory, isFile}

ssh.stat "server" "/var/log/app.log"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
remotePath	string	Yes	Remote path

---

readFile

Read the contents of a remote file as a string

Module: ssh | Returns: string -- File content as UTF-8 string

ssh.readFile "server" "/etc/hostname"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
remotePath	string	Yes	Remote file path

---

writeFile

Write string content to a remote file

Module: ssh | Returns: boolean -- True on success

ssh.writeFile "server" "/tmp/config.txt" "key=value"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier
remotePath	string	Yes	Remote file path
content	string	Yes	Content to write

---

close

Close an SSH connection

Module: ssh | Returns: boolean -- True if closed, false if not found

ssh.close "server"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier

---

isConnected

Check if an SSH connection is alive

Module: ssh | Returns: boolean -- True if connected

ssh.isConnected "server"

Parameter	Type	Required	Description
connectionId	string	Yes	Connection identifier

---

Error Handling

All functions throw on failure. Common errors:

Error	Cause
SSH connection "..." not found	Check the error message for details

@desc "Exec and validate result"
do
  set $result as ssh.exec "server" "ls -la /var/log"
  if $result != null
    print "Success"
  else
    print "No result"
  end
enddo

Recipes

1. Multi-step SSH workflow

Chain multiple ssh operations together.

@desc "Connect, exec, and more"
do
  set $r_connect as ssh.connect "server" {"host": "example.com", "username": "admin", "password": "..."}
  set $r_exec as ssh.exec "server" "ls -la /var/log"
  set $r_upload as ssh.upload "server" "./deploy.tar.gz" "/opt/app/deploy.tar.gz"
  print "All operations complete"
enddo

2. Safe connect with validation

Check results before proceeding.

@desc "Connect and validate result"
do
  set $result as ssh.connect "server" {"host": "example.com", "username": "admin", "password": "..."}
  if $result != null
    print "Success: " + $result
  else
    print "Operation returned no data"
  end
enddo

Related Modules

• json -- JSON module for complementary functionality