{"library":"ssh2-sftp-client","title":"Node.js SFTP Client (Promise-based)","type":"library","description":"ssh2-sftp-client is a promise-based SFTP client for Node.js, acting as a decorator around the robust `ssh2` package. It provides a convenient, promise-driven API for common SFTP operations such as connecting, listing directories, uploading, downloading, and managing files, abstracting away the event-based complexities of the underlying `ssh2` library. The current stable release is v12.1.1, indicating active maintenance with a regular cadence of minor and patch updates, alongside major versions for significant API changes. It officially supports Node.js versions 20.x and newer, specifically tested against Node 24.14.0, and includes specific fixes for platform quirks like those found in Microsoft SFTP servers. Its focus on promises, active bug fixing, and direct integration with the `ssh2` library makes it a reliable solution for SFTP interactions in modern Node.js environments.","language":"javascript","status":"active","last_verified":"Sun Apr 19","install":{"commands":["npm install ssh2-sftp-client"],"cli":null},"imports":["import SftpClient from 'ssh2-sftp-client';","const SftpClient = require('ssh2-sftp-client');","import type { ConnectConfig } from 'ssh2-sftp-client';"],"auth":{"required":false,"env_vars":[]},"links":{"homepage":null,"github":"https://github.com/theophilusx/ssh2-sftp-client","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/ssh2-sftp-client","openapi_spec":null,"status_page":null,"smithery":null},"quickstart":{"code":"import SftpClient from 'ssh2-sftp-client';\nimport path from 'path';\nimport fs from 'fs/promises';\n\nasync function sftpExample() {\n  const sftp = new SftpClient();\n  const host = process.env.SFTP_HOST ?? 'sftp.example.com';\n  const port = parseInt(process.env.SFTP_PORT ?? '22', 10);\n  const username = process.env.SFTP_USERNAME ?? 'user';\n  const password = process.env.SFTP_PASSWORD ?? 'password'; // Or use privateKey: fs.readFileSync('~/.ssh/id_rsa')\n  const remoteDir = '/home/user/uploads';\n  const remoteFile = path.join(remoteDir, 'test_upload.txt');\n  const localFileToUpload = 'local_file.txt';\n  const localFileToDownload = 'downloaded_file.txt';\n\n  try {\n    console.log(`Attempting to connect to ${username}@${host}:${port}...`);\n    await sftp.connect({ host, port, username, password });\n    console.log('Successfully connected to SFTP server.');\n\n    // Ensure the remote directory exists\n    await sftp.mkdir(remoteDir, true);\n\n    // Create a dummy local file for upload\n    await fs.writeFile(localFileToUpload, 'Hello from Node.js SFTP client!');\n    console.log(`Uploading ${localFileToUpload} to ${remoteFile}...`);\n    await sftp.put(localFileToUpload, remoteFile);\n    console.log('File uploaded successfully.');\n\n    // List contents of the remote directory\n    console.log(`Listing contents of ${remoteDir}:`);\n    const list = await sftp.list(remoteDir);\n    list.forEach(item => console.log(`  - ${item.name} (${item.type})`));\n\n    // Download the uploaded file\n    console.log(`Downloading ${remoteFile} to ${localFileToDownload}...`);\n    await sftp.get(remoteFile, localFileToDownload);\n    console.log('File downloaded successfully.');\n\n    // Verify downloaded content (optional)\n    const downloadedContent = await fs.readFile(localFileToDownload, 'utf8');\n    console.log('Downloaded content:', downloadedContent);\n\n    // Delete the remote file\n    console.log(`Deleting remote file ${remoteFile}...`);\n    await sftp.delete(remoteFile);\n    console.log('Remote file deleted.');\n\n  } catch (err) {\n    console.error('SFTP operation failed:', err.message);\n  } finally {\n    if (sftp.sftp) { // Check if the internal SFTP object exists (implies connection was made)\n      console.log('Disconnecting from SFTP server.');\n      await sftp.end();\n    }\n    // Clean up local test files\n    await fs.unlink(localFileToUpload).catch(() => {});\n    await fs.unlink(localFileToDownload).catch(() => {});\n    console.log('Local temporary files cleaned up.');\n  }\n}\n\nsftpExample();","lang":"typescript","description":"Demonstrates connecting to an SFTP server, creating a directory, uploading, listing, downloading, and deleting a file, including error handling and resource cleanup.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}