Skip to main content

SFTP

The SFTP functions provide file operations on a remote server over SFTP (SSH File Transfer Protocol). They can be used to list, upload, download, move, and remove files and directories on a remote host.

All SFTP functions require an account parameter, which should be the name of an account of type "SSH/SFTP" configured on the Accounts tab, and which provides the connection details (host, port, credentials). Each function call opens a new connection, performs the operation, and closes the connection.

Complete example​

// Upload a report to the SFTP server
let report = "id,name,status\n1,Alice,active\n2,Bob,inactive";
sftp_upload("my-sftp", "/uploads/report.csv", report);

// Verify the file was uploaded
let exists = sftp_stat_exists("my-sftp", "/uploads/report.csv");
if (exists) {
  log("uploaded report, size:", exists.size);
}

// List the contents of the uploads directory
let files = sftp_list("my-sftp", "/uploads");
for (let entry of files) {
  log("file:", entry.filename);
  log("size:", entry.attrs.size);
}

// Download and process the file
let downloaded = sftp_download("my-sftp", "/uploads/report.csv");
let text = downloaded.toString();

// Move the file to an archive directory
sftp_mkdir("my-sftp", "/archive");
sftp_move("my-sftp", "/uploads/report.csv", "/archive/report.csv");

sftp_download​

Downloads a file from the SFTP server.

let file = sftp_download(account, filePath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: path of the file to download.

Returns: a Buffer containing the file content. Use .toString() to convert to a string.

Example:

let file = sftp_download("my-sftp", "/data/report.csv");
let text = file.toString();
log("content:", text);

sftp_is_directory​

Returns true when the provided path is a directory, false otherwise.

let isDirectory = sftp_is_directory(account, filePath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: path to check. Default: .

sftp_is_file​

Returns true when the provided path is a regular file, false otherwise.

let isFile = sftp_is_file(account, filePath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: path to check. Default: .

sftp_list​

Returns a list of files and directories at the specified path.

let list = sftp_list(account, filePath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: path to list. Default: .

Returns: an array of entry objects, each with filename, longname, and attrs properties. The exact properties present in attrs depend on the SFTP server, but typically include size, uid, gid, mode, atime, and mtime.

Example:

let list = sftp_list("my-sftp", "/data");
// list = [
//   {
//     filename: "report.csv",
//     longname: "-rw-r--r-- 1 user group 1024 Jan 01 12:00 report.csv",
//     attrs: { size: 1024, uid: 1000, gid: 1000, mode: 33188, atime: 1704106800, mtime: 1704106800 }
//   },
//   {
//     filename: "archive",
//     longname: "drwxr-xr-x 2 user group 4096 Jan 01 12:00 archive",
//     attrs: { size: 4096, uid: 1000, gid: 1000, mode: 16877, atime: 1704106800, mtime: 1704106800 }
//   }
// ]

sftp_mkdir​

Creates a directory at the specified path.

sftp_mkdir(account, filePath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: path of the directory to create.

sftp_move​

Moves a file or directory from one path to another. This is an alias for sftp_rename.

sftp_move(account, sourcePath, targetPath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • sourcePath: path of the file or directory to move.
  • targetPath: destination path.

sftp_remove​

Removes a file at the specified path. To remove a directory, use sftp_rmdir instead.

sftp_remove(account, filePath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: path of the file to remove.

sftp_rename​

Renames a file or directory.

sftp_rename(account, sourcePath, targetPath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • sourcePath: current path of the file or directory.
  • targetPath: new path.

sftp_rmdir​

Removes an empty directory at the specified path.

sftp_rmdir(account, filePath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: path of the empty directory to remove.

sftp_stat​

Returns file or directory statistics for the specified path. Raises an error if the path does not exist.

let stats = sftp_stat(account, filePath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: path to check. Default: .

Returns: a stats object. The exact properties depend on the SFTP server, but typically include size, uid, gid, mode, atime, and mtime.

Example:

let stats = sftp_stat("my-sftp", "/data/report.csv");
// stats = { size: 1024, uid: 1000, gid: 1000, mode: 33188, atime: 1704106800, mtime: 1704106800 }
log("file size:", stats.size);

sftp_stat_exists​

Checks if a file or directory exists at the specified path. Returns the stats object if it exists, or false if it doesn't. Unlike sftp_stat, this function does not raise an error when the path does not exist.

let result = sftp_stat_exists(account, filePath);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: path to check. Default: .

Returns: a stats object (same as sftp_stat) if the path exists, false otherwise.

Example:

let result = sftp_stat_exists("my-sftp", "/data/report.csv");
if (result) {
  log("file exists, size:", result.size);
} else {
  log("file does not exist");
}

sftp_upload​

Uploads content to a file on the SFTP server. Creates the file if it doesn't exist, or overwrites it if it does.

sftp_upload(account, filePath, fileContent);

Parameters:

  • account: name of an account of type "SSH / SFTP".
  • filePath: destination path for the file.
  • fileContent: a string or Buffer containing the content to upload.

Example:

sftp_upload("my-sftp", "/data/report.csv", "id,name\n1,Alice\n2,Bob");