ssh2-sftp-client

What is ssh2-sftp-client?

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.

What are ssh2-sftp-client's main functionalities?

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);
});

Other packages similar to ssh2-sftp-client

ssh2

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.

node-sftp

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.

scp2

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.

README

SSH2 SFTP Client

a SFTP client for node.js, a wrapper for ssh2

Installation

npm install ssh2-sftp-client

Usage

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');
});

Documentation

the connection to server config pls see ssh2 client event.

list of methods: all the methods will return a Promise;

List

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

Get a Chunk 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 'utf8'.

Before V3.0.0, get method will return new readable stream from remotePath.

sftp.get(remoteFilePath, [useCompression], [encoding], [addtionalOptions]);

Put

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, [useCompression], [encoding], [addtionalOptions]);
sftp.put(Buffer, remoteFilePath, [useCompression], [encoding], [addtionalOptions]);
sftp.put(Stream, remoteFilePath, [useCompression], [encoding], [addtionalOptions]);

Mkdir

create a new directory.

// recursive default is false, if true, it will create directory recursive
sftp.mkdir(remoteFilePath, recursive);

Rmdir

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

delete file.

sftp.delete(remoteFilePath);

Rename

rename remoteSourcePath to remoteDestPath (removes remoteSourcePath).

sftp.rename(remoteSourcePath, remoteDestPath);

Chmod

modify rights to remoteDestPath file

sftp.chmod(remoteDestPath, mode);

Connect

connection config you will see here

End

close the sftp connection. when you need it, you can call it in then() or catch().

sftp.end();

Event

add client event handle. you can find more here

close

The socket was closed. hadError is set to true if this was due to error.

sftp.on('close', callbackFn)

end

The socket was disconnected.

sftp.on('end', callbackFn)

error

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)

FAQ

Log

V3.0.0

- change: `sftp.get` will return chunk not stream anymore
- fix: get readable not emitting data events in node 10.0.0

V2.1.1

- 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)

V2.0.1

- 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)

V1.1.0

- fix: add encoding control support for binary stream

V1.0.5:

- fix: multi image upload
- change: remove `this.client.sftp` to `connect` function