ssh2-sftp-client
Advanced tools
The ssh2-sftp-client npm package is a promise-based SFTP client for Node.js, built on top of the ssh2 module. It provides a simple and easy-to-use interface for performing various SFTP operations such as uploading, downloading, listing, and deleting files on a remote server.
Connecting to an SFTP server
This feature allows you to establish a connection to an SFTP server using the provided host, port, username, and password.
const Client = require('ssh2-sftp-client');
const sftp = new Client();
sftp.connect({
host: 'example.com',
port: '22',
username: 'username',
password: 'password'
}).then(() => {
console.log('Connected');
}).catch(err => {
console.error(err.message);
});Uploading a file
This feature allows you to upload a file from your local system to the remote SFTP server.
sftp.put('local/path/to/file.txt', 'remote/path/to/file.txt').then(() => {
console.log('File uploaded');
}).catch(err => {
console.error(err.message);
});Downloading a file
This feature allows you to download a file from the remote SFTP server to your local system.
sftp.get('remote/path/to/file.txt', 'local/path/to/file.txt').then(() => {
console.log('File downloaded');
}).catch(err => {
console.error(err.message);
});Listing files in a directory
This feature allows you to list all files and directories in a specified remote directory.
sftp.list('remote/path/to/directory').then(data => {
console.log(data);
}).catch(err => {
console.error(err.message);
});Deleting a file
This feature allows you to delete a specified file from the remote SFTP server.
sftp.delete('remote/path/to/file.txt').then(() => {
console.log('File deleted');
}).catch(err => {
console.error(err.message);
});The ssh2 package is a general-purpose SSH2 client and server module for Node.js. It provides a lower-level API compared to ssh2-sftp-client, allowing for more granular control over SSH and SFTP operations. However, it requires more boilerplate code to accomplish the same tasks.
The node-sftp package is another SFTP client for Node.js. It offers similar functionalities to ssh2-sftp-client but is less popular and has fewer features. It is also not as actively maintained as ssh2-sftp-client.
The scp2 package is a client for SCP (Secure Copy Protocol) in Node.js. While it provides functionalities for transferring files over SSH, it is limited to SCP and does not support the full range of SFTP operations that ssh2-sftp-client does.
a SFTP client for node.js, a wrapper for ssh2
Additional documentation on the methods and available options can be found in the ssh2 and ssh2-streams documentation.
npm install ssh2-sftp-client
let Client = require('ssh2-sftp-client');
let sftp = new Client();
sftp.connect({
host: '127.0.0.1',
port: '8080',
username: 'username',
password: '******'
}).then(() => {
return sftp.list('/pathname');
}).then((data) => {
console.log(data, 'the data info');
}).catch((err) => {
console.log(err, 'catch error');
});
Due to some incompatibilities with stream handling which breaks this module when used with Node 10.x, some changes have been implemented that should enhance the interface, but which also break compatibility with previous versions.
const defaults = {
highWaterMark: 32 * 1024,
debug: undefined,
concurrency: 64,
chunkSize: 32768,
step: undefined,
mode: 0o666,
autoClose: true,
encoding: null
};
Used to retrieve a file from a remote SFTP server.
the connection to server config pls see ssh2 client event.
list of methods: all the methods will return a Promise;
Retrieves a directory listing.
sftp.list(remoteFilePath)
directory info:
type: // file type(-, d, l)
name: // file name
size: // file size
modifyTime: // file timestamp of modified time
accessTime: // file timestamp of access time
rights: {
user:
group:
other:
},
owner: // user ID
group: // group ID
Get a ReadableStream from remotePath. The encoding is passed to Node Stream (https://nodejs.org/api/stream.html) and it controls how the content is encoded. For example, when downloading binary data, 'null' should be passed (check node stream documentation). Default to 'null'.
sftp.get(remoteFilePath, [options]);
Downloads a file at remotePath to localPath using parallel reads for faster throughput. options properties you can find fastGet method here.
sftp.fastGet(remotePath, localPath, [options]);
upload a file from localPath or Buffer, Stream data to remoteFilePath.The encoding is passed to Node Stream to control how the content is encoded. Default to 'utf8'.
sftp.put(localFilePath, remoteFilePath, [optons]);
sftp.put(Buffer, remoteFilePath, [options]);
sftp.put(Stream, remoteFilePath, [options]);
Uploads a file from localPath to remotePath using parallel reads for faster throughput. options properties you can find fastPut method here.
sftp.fastPut(localPath, remotePath, [options]);
create a new directory.
// recursive default is false, if true, it will create directory recursive
sftp.mkdir(remoteFilePath, recursive);
remove the directory or file.
// recursive default is false, if true, it will remove directory recursive even if is not empty
sftp.rmdir(localPath, recursive);
delete file.
sftp.delete(remoteFilePath);
rename remoteSourcePath to remoteDestPath (removes remoteSourcePath).
sftp.rename(remoteSourcePath, remoteDestPath);
modify rights to remoteDestPath file
sftp.chmod(remoteDestPath, mode);
connection config you will see here
close the sftp connection. when you need it, you can call it in then() or catch().
sftp.end();
add client event handle. you can find more here
The socket was closed. hadError is set to true if this was due to error.
sftp.on('close', callbackFn)
The socket was disconnected.
sftp.on('end', callbackFn)
An error occurred. A 'level' property indicates 'client-socket' for socket-level errors and 'client-ssh' for SSH disconnection messages. In the case of 'client-ssh' messages, there may be a 'description' property that provides more detail.
sftp.on('error', callbackFn)
- merge #108, #110
- fix connect promise if connection ends
- merge #105
- fix windows path
- merge pr #99, #100
- bug fix
Requires node.js v7.5.0 or above.
- merge pr #97, thanks for @theophilusx
- Remove emmitter.maxListener warnings
- Upgraded ssh2 dependency from 0.5.5 to 0.6.1
- Enhanced error messages to provide more context and to be more consistent
- re-factored test
- Added new 'exists' method and re-factored mkdir/rmdir
- add: `stat` method
- add `fastGet` and `fastPut` method.
- fix: `mkdir` file exists decision logic
- change: `sftp.get` will return chunk not stream anymore
- fix: get readable not emitting data events in node 10.0.0
- add: event listener. [doc](https://github.com/jyu213/ssh2-sftp-client#Event)
- add: `get` or `put` method add extra options [pr#52](https://github.com/jyu213/ssh2-sftp-client/pull/52)
- add: `chmod` method [pr#33](https://github.com/jyu213/ssh2-sftp-client/pull/33)
- update: upgrade ssh2 to V0.5.0 [pr#30](https://github.com/jyu213/ssh2-sftp-client/pull/30)
- fix: get method stream error reject unwork [#22](https://github.com/jyu213/ssh2-sftp-client/issues/22)
- fix: return Error object on promise rejection [pr#20](https://github.com/jyu213/ssh2-sftp-client/pull/20)
- fix: add encoding control support for binary stream
- fix: multi image upload
- change: remove `this.client.sftp` to `connect` function
FAQs
ssh2 sftp client for node
The npm package ssh2-sftp-client receives a total of 507,923 weekly downloads. As such, ssh2-sftp-client popularity was classified as popular.
We found that ssh2-sftp-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.