MODLR

FTPClient ​

Transfers files and manages directories on a remote FTP, FTPS or SFTP server.

js
const client = ftp.ConnectWithSecret("sftp", "files.partner.com", 22, "modlr", "PARTNER_SFTP_KEY");

if (!client.IsConnected()) {
    script.fail("Could not connect to the partner SFTP server.");
}

client.Download("/outbound/sales.csv", "uploads/sales.csv");

Constructors ​

There are three ways to connect, depending on how the server authenticates. All three take the same first four parameters:

ParameterTypeDescription
protocolstring"ftp", "ftps" (FTP over TLS) or "sftp" (SFTP over SSH). Any other value is treated as "ftp".
hostnamestringThe server's host name or IP address.
portnumberThe port to connect on. There's no default: usually 21 for FTP and FTPS, and 22 for SFTP.
usernamestringThe user name to log in with.

A failed connection is logged rather than thrown, so check IsConnected() before transferring anything.

ftp.ConnectWithSecret ftp.ConnectWithSecret(protocol, hostname, port, username, keySecret, passphraseSecret) FTPClient ^v3.0.0 ​

Connects to an SFTP server with a private key stored as a Secret. This is the preferred way to use a key: you pass the secret's name, so the key never appears in the process.

ParameterTypeDescription
keySecretstringThe name of the secret holding the private key.
passphraseSecretstringOptional. The name of the secret holding the key's passphrase. Leave it out when the key isn't encrypted.
js
const client = ftp.ConnectWithSecret("sftp", "files.partner.com", 22, "modlr", "PARTNER_SFTP_KEY");

// A passphrase-protected key
const client = ftp.ConnectWithSecret("sftp", "files.partner.com", 22, "modlr", "PARTNER_SFTP_KEY", "PARTNER_SFTP_PASSPHRASE");

ftp.ConnectWithKeyFile ftp.ConnectWithKeyFile(protocol, hostname, port, username, keyFile, passphrase) FTPClient ​

Connects to an SFTP server with a private key file.

ParameterTypeDescription
keyFilestringThe path of the private key file.
passphrasestringOptional. The key's passphrase. Leave it out when the key isn't encrypted.
js
const client = ftp.ConnectWithKeyFile("sftp", "files.partner.com", 22, "modlr", "keys/partner_rsa");

ftp.Connect ftp.Connect(protocol, hostname, port, username, password) FTPClient ​

Connects with a user name and password.

ParameterTypeDescription
passwordstringThe password to log in with.
js
const client = ftp.Connect("sftp", "files.partner.com", 22, "modlr", security.getSecret("PARTNER_SFTP_PASSWORD"));

Overview ​

  • Check the connection: connecting never throws, so call IsConnected() straight after connecting.
  • Check each transfer: methods return false (or null for Directory()) when they fail, and write the reason to the process log. They don't throw.
  • Destination directories must exist: Upload() and Rename() fail if the remote directory isn't there. Create it with MakeDirectory() first.
  • Timeouts: there's no timeout by default, so an unresponsive server can hold up a process. Set one with SetTimeout() for servers you don't control.
  • Disconnecting: the client disconnects automatically when the process finishes.

Methods ​

IsConnected IsConnected() boolean ​

Returns true when the client is connected to the server. Returns false if the connection failed, or after Disconnect().

SetTimeout SetTimeout(milliseconds) ​

Sets how long each operation, such as a listing or a transfer, can take before it's abandoned. An operation that times out fails like any other, returning false or null.

ParameterTypeDescription
millisecondsnumberThe timeout for each operation, in milliseconds. 0 means no timeout.

Directory Directory(directory) string | null ​

Lists the files and folders directly inside a remote directory. Returns a JSON string, so read it with JSON.parse(). Returns null if the listing fails.

ParameterTypeDescription
directorystringThe remote directory, for example "/outbound". A trailing slash makes no difference.

Each entry has:

  • name: the file or folder name.
  • path: its full remote path, ready to pass to Download().
  • isDirectory: true for folders.
  • size: its size in bytes.

Download Download(remote, local) boolean ​

Downloads a remote file. Returns true when the file transferred.

ParameterTypeDescription
remotestringThe remote file's path.
localstringThe path to save it to.

Upload Upload(localPath, remoteDirectory) boolean ​

Uploads a file into a remote directory. The file keeps its name, so pass the directory, not a file path. Returns true when the file transferred.

ParameterTypeDescription
localPathstringThe path of the file to upload.
remoteDirectorystringThe remote directory to upload into. It must already exist.

MakeDirectory MakeDirectory(remote) boolean ​

Creates a remote directory. Only the last folder in the path is created, so its parent must already exist. Returns false if it fails, including when the directory already exists.

ParameterTypeDescription
remotestringThe remote directory to create.

Rename Rename(remote, remoteNew) boolean ​

Renames a remote file. The new path can be in a different directory, which moves the file. Returns true when it succeeds.

ParameterTypeDescription
remotestringThe file's current remote path.
remoteNewstringIts new remote path. The directory must already exist.

Delete Delete(remote) boolean ​

Deletes a remote file. This can't be undone, so consider moving the file into an archive directory with Rename() instead. Returns true when it succeeds.

ParameterTypeDescription
remotestringThe remote file's path.

Disconnect Disconnect() optional ​

Closes the connection. The client disconnects automatically when the process finishes, so only call this to end the session early. A disconnected client can't be reused; connect again to make a new one.

Examples ​

Download new files and archive them ​

js
const client = ftp.ConnectWithSecret("sftp", "files.partner.com", 22, "modlr", "PARTNER_SFTP_KEY");

if (!client.IsConnected()) {
    script.fail("Could not connect to the partner SFTP server.");
}

client.MakeDirectory("/outbound/archive");

for (const entry of JSON.parse(client.Directory("/outbound"))) {
    if (entry.isDirectory || !entry.name.endsWith(".csv")) {
        continue;
    }

    if (client.Download(entry.path, "uploads/" + entry.name)) {
        client.Rename(entry.path, "/outbound/archive/" + entry.name);
    }
}

Upload a report ​

js
const client = ftp.ConnectWithSecret("sftp", "files.partner.com", 22, "modlr", "PARTNER_SFTP_KEY");

if (!client.Upload("exports/report.xlsx", "/inbound")) {
    script.fail("Failed to upload the report.");
}

Connect over FTP or FTPS ​

js
// FTP
const client = ftp.Connect("ftp", "files.partner.com", 21, "modlr", security.getSecret("PARTNER_FTP_PASSWORD"));

// FTPS (FTP over TLS)
const client = ftp.Connect("ftps", "files.partner.com", 21, "modlr", security.getSecret("PARTNER_FTP_PASSWORD"));

if (!client.IsConnected()) {
    script.fail("Could not connect to the partner FTP server.");
}

Copyright © 2026 MODLR