# 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()
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.medable.com/cortex-api/scripting/modules-1/sftp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.