# SFTP

```javascript
const sftp = require('sftp')
```

The Secure File Transfer Protocol (SFTP) modules allow scripts to access an SFTP server.

{% hint style="info" %}
**Note:** You must have access to an FTP server and know the following values: \
**host***,* **port***,* **username***,* and **password***.*
{% endhint %}

{% hint style="success" %}
**Tip:** To enable SFTP for your environment, please contact support.
{% endhint %}

## module SFTP

### create(options)

Creates a new connection and client.

*Arguments*

* `options` { Object }
  * `host` { String } Server domain name or IP address.
  * `port` { Number = *`22`* } SFTP server port.
  * `username` { String } Username for authentication.
  * `password` { String } Password for authentication.
  * `privateKey` { String } String containing a private key for key-based or host-based user authentication.
  * `passphrase` { String } The passphrase to decrypt an encrypted private key.
  * `localHostname` { String } Along with `localUsername` and `privateKey`, set this to a non-empty string for host-based user authentication.
  * `localUsername` { String } Along with `localHostname` and `privateKey`, set this value to a non-empty string for host-based user authentication.
  * `hostHash` { String = *`md5`* } A valid hash algorithm to check against the host fingerprint.
  * `hostFingerprint` { String } Use together with `hostHash` to verify the host fingerprint.

*Returns*

* { sftp.Client } A new client instance.

### list()

Lists current script connections.

*Returns*

* { Client\[] } Active connections for this script.

## class sftp.Client

SFTP client. To create a client, use `sftp.create(options)`.

### chmod(path, mode)

Modifies permissions.

*Arguments*

* `path` { String } The resource to modify.
* `mode` { String } A string containing octal numbers.

### close()

Closes the connection with the server.

{% hint style="info" %}
**Note:** Connections are automatically closed when a script exits, which frees up resources to open another connection.
{% endhint %}

### delete(path)

Deletes a resource.

*Arguments*

* `path` { String } The resource to delete.

### exists(path)

Checks for the existence of a filesystem resource.

*Arguments*

* `path` { String } The path to check.

*Returns*

* { Boolean } True if the resource exists.

### get(path)

Retrieves a file.

*Arguments*

* `path` { String } The path to read.

*Returns*

* { Buffer } A buffer containing the file data.

### list(path)

Reads the contents of a remote directory.

*Arguments*

* `path` { String } The path to read.

*Returns*

* { Object\[] } A list of directory contents.
  * `type` { String } Entry type.
  * `name` { String } Entry name.
  * `size` { Number } Size in bytes.
  * `modifyTime` { Number } Modified time in milliseconds.
  * `accessTime` { Number } Last access time in milliseconds.
  * `rights` { Object }
    * `user` { String } User access rights (rwx).
    * `group` { String } Group access rights (rwx).
    * `other` { String } Other access rights (rwx).
  * `owner` { Number } Owner uid.
  * `group` { Number } Group gid.

### mkdir(path)

Creates a directory.

*Arguments*

* `path` { String } The directory to create.

### put(path, data)

Uploads a file.

*Arguments*

* `path` { String } The path to write.
* `data` { Buffer } A buffer containing the file data.

### rename(path, to)

Renames a resource.

*Arguments*

* `path` { String } The resource to rename.
* `to` { String } The target resource name.

### stat(path)

Reads a filesystem resource's stats.

*Arguments*

* `path` { String } The path to read.

*Returns*

* { Object } A resource stats object.
  * `mode` { Number } Mode for the resource.
  * `permissions` { String } Resource permissions.
  * `size` { Number } Size in bytes.
  * `modifyTime` { Number } Modified time in milliseconds.
  * `accessTime` { Number } Last access time in milliseconds.
  * `owner` { Number } Owner uid.
  * `group` { Number } Group gid.

## Examples

```javascript
const sftp = require('sftp'),
      conn = sftp.create({
        host: 'sftp.example.org',
        port: 22,
        username: 'foo',
        password: 'this is a passphrase.'
      }),
      buffer = new Buffer('ok!'),      
      home = '/home/foo'

if (!conn.exists(`${home}/test`)) {
  conn.mkdir(`${home}/test`)
}
if (!conn.exists(`${home}/test/test.txt`)) {
  conn.put(`${home}/test/test.txt`, buffer)
}
conn.close()
```