SftpSession

A session on an SFTP server: upload, download, list, create and delete files and directories. The connection is made by the first operation and re-made when it was dropped or after close(). All operations return the session, so they can be chained.

• Kind Object
• Library Sftp
• Category Remote & Infrastructure
• Functions 10

How to get one

1. Sftp .newSession()
2. SftpSession

local sftp = Sftp.newSession(username, password, host)

Returned by

• Sftp.newSession()

Functions

• setPrivateKey self Adds a private key file for key based login.
• setPrivateKeyFileWithPassphrase self Like setPrivateKey, for a key file that is protected by a passphrase.
• downloadFileTo self Downloads a remote file into the project.
• uploadFileTo self Uploads a project file (fetched from the Reflex server first when it is not in the workspace).
• deleteFile self Deletes a file on the server.
• deleteDirectory self Deletes a directory on the server.
• createDirectory self Creates one directory on the server.
• listFiles table Lists the names of the entries in a directory, files and subdirectories alike, without the special entries "." and "..".
• setPermissionsOfTo self Sets the Unix permissions (chmod) of a remote file or directory.
• close self Closes the connection.

setPrivateKey()

sftp.setPrivateKey(privateKey: string)→self

Adds a private key file for key based login. The path is a file in the project (fetched from the Reflex server when it is not in the workspace). Closes the current connection, so the next operation logs in with the key. Call it before the first operation. Raises "Failed setting private key: ..." when the file cannot be read as a key.

Parameters

privateKey string

Private key file in the project

Returns

self chainable The sftp itself, so calls can be chained.

Example

sftp.setPrivateKey("keys/deploy_ed25519")

setPrivateKeyFileWithPassphrase()

sftp.setPrivateKeyFileWithPassphrase(privateKey: string, passphrase: string)→self

Like setPrivateKey, for a key file that is protected by a passphrase. Closes the current connection.

Parameters

privateKey string

Private key file in the project

passphrase string

Passphrase of the key; use secret()

Returns

self chainable The sftp itself, so calls can be chained.

Example

sftp.setPrivateKeyFileWithPassphrase("keys/deploy_rsa", secret("deploy_key_passphrase"))

downloadFileTo()

sftp.downloadFileTo(remoteFile: string, localFile: string)→self

Downloads a remote file into the project. Missing local folders are created and an existing local file is overwritten. Raises "Failed to download: <remote file> Error: ..." when the remote file does not exist or cannot be read.

Parameters

remoteFile string

Path of the file on the server

localFile string

Path in the project to save the file as

Returns

self chainable The sftp itself, so calls can be chained.

Example

sftp.downloadFileTo("/outgoing/orders.csv", "input/orders.csv")

uploadFileTo()

sftp.uploadFileTo(localFile: string, remoteFile: string)→self

Uploads a project file (fetched from the Reflex server first when it is not in the workspace). The remote file is overwritten when it exists; the remote directory must already exist (use createDirectory). Raises "Failed to upload <local> to <remote> Error: ..." on failure.

Parameters

localFile string

Path of the file in the project

remoteFile string

Path on the server to write the file to

Returns

self chainable The sftp itself, so calls can be chained.

Example

sftp.createDirectory("/incoming/2026")
sftp.uploadFileTo("output/report.csv", "/incoming/2026/report.csv")

deleteFile()

sftp.deleteFile(remoteFile: string)→self

Deletes a file on the server. Raises an error when it does not exist or cannot be deleted.

Parameters

remoteFile string

Path of the file on the server

Returns

self chainable The sftp itself, so calls can be chained.

deleteDirectory()

sftp.deleteDirectory(remoteDir: string)→self

Deletes a directory on the server. The directory must be empty; delete its files first.

Parameters

remoteDir string

Path of the directory on the server

Returns

self chainable The sftp itself, so calls can be chained.

createDirectory()

sftp.createDirectory(remoteDir: string)→self

Creates one directory on the server. It is not recursive: the parent must exist, and an existing directory is an error.

Parameters

remoteDir string

Path of the new directory on the server

Returns

self chainable The sftp itself, so calls can be chained.

listFiles()

sftp.listFiles(remoteDir: string)→table

Lists the names of the entries in a directory, files and subdirectories alike, without the special entries "." and "..". Only names are returned, no sizes or types. The path is used as given, like in the other functions: a relative path (or "" and ".") starts in the login directory, a path starting with "/" in the server root.

Parameters

remoteDir string

Directory on the server; relative to the login directory

Returns

table List of entry names

Example

for _, name in ipairs(sftp.listFiles("outgoing")) do
    if name:match("%.csv$") then
        sftp.downloadFileTo("/outgoing/" .. name, "input/" .. name)
    end
end

setPermissionsOfTo()

sftp.setPermissionsOfTo(remoteFile: string, chmodPermissions: string)→self

Sets the Unix permissions (chmod) of a remote file or directory. The permissions are an octal string such as "644" or "755"; anything else is an error.

Parameters

remoteFile string

Path of the file or directory on the server

chmodPermissions string

Octal permissions, for example "644"

Returns

self chainable The sftp itself, so calls can be chained.

Example

sftp.setPermissionsOfTo("/incoming/report.csv", "640")

close()

sftp.close()→self

Closes the connection. The next operation connects again.

Returns

self chainable The sftp itself, so calls can be chained.