# FTP

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

The File Transfer Protocol (FTP) module allows scripts to access an FTP 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 FTP for your environment, please contact support.
{% endhint %}

## module FTP

### create(options)

Connects an FTP client instance to a remote FTP server.

{% hint style="success" %}
**Tip:** If you set the `host` with an IP address, you should also set the secureOption `rejectUnauthorized` to `false` to avoid potential conflicts with the domain name on the server certificate, as provided by the TLS Server Name Indication (SNI) extension.
{% endhint %}

*Arguments*

* `options` { Object }
  * `host` { String = *localhost* } FTP server domain name or IP address.
  * `port` { Number = `21` } FTP server port.
  * `username` { String = `anonymous` } Username for authentication.
  * `password` { String = `anonymous@` } Password for authentication.
  * `connTimeout` { Number = `10000` } Wait time in milliseconds to establish a control connection.
  * `pasvTimeout` { Number = `10000` } Wait time in milliseconds to establish a `PASV` data connection.
  * `keepalive` { Number = `10000` } Wait time in milliseconds to send a dummy (NOOP) command to keep the connection alive.
  * `secure` { String = `true` } Always set to `true` for control and data encryption.
  * `secureOptions` { Object } Additional options to be passed to `tls.connect()`, as listed below. For more details, view the [Node.js TLS module reference](https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions).
    * `ca` { String, String\[], Buffer, Buffer\[] } Overrides default Certificate Authority (CA) certificates.
    * `cert` { String, String\[], Buffer, Buffer\[] } Defines certification chains in Privacy-Enhanced Mail (PEM) format.
    * `sigalgs` { String } Defines a list of supported signature algorithms. 
    * `ciphers` { String } Replaces the cipher suite specification.
    * `crl` { String, String\[], Buffer, Buffer\[] } Defines PEM-formatted Certificate Revocation Lists (CRLs).
    * `dhparam` { String, Buffer } Defines Diffie–Hellman parameters.
    * `ecdhCurve` { String } Describes a named curve or a colon-separated list of curve NIDs or names to use for Elliptic-curve Diffie–Hellman (ECDH) key agreement. \
      **Default: ⁠**[`tls.DEFAULT_ECDH_CURVE`](https://nodejs.org/api/tls.html#tlsdefault_ecdh_curve).
    * `honorCipherOrder` { Boolean } Attempts to use the cipher suite preferences of the server instead of the client.
    * `key` { String, String\[], Buffer, Buffer\[], Object\[] } Sets private keys in PEM format.
    * `minVersion` { String } Allows you to choose the minimum allowable TLS version from the following: `'TLSv1.3'`, `'TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. \
      **Default:** [`tls.DEFAULT_MIN_VERSION`](https://nodejs.org/api/tls.html#tlsdefault_min_version).
    * `maxVersion` { String } Allows you to choose the maximum allowable TLS version from the following: `'TLSv1.3'`, `'TLSv1.2'`, `'TLSv1.1'`, or `'TLSv1'`. This option cannot be used in conjunction with `secureProtocol`; you can only use one or the other. **Default:** [`tls.DEFAULT_MAX_VERSION`](https://nodejs.org/api/tls.html#tlsdefault_max_version).
    * `passphrase` { String } Shared passphrase used for a single private key or a PFX.
    * `pfx` { String, String\[], Buffer, Buffer\[], Object\[] } Defines the PFX or PKCS12 encoded private key and certificate chain.
    * `secureProtocol` { String } Provides a legacy mechanism to select the TLS protocol version to use. It does not support independent control of the minimum and maximum versions. It also does not support limiting the protocol to TLSv1.3. If you wish to do so, use `minVersion` and `maxVersion` instead. **Default:** none, see `minVersion`.
    * `rejectUnauthorized` { Boolean = `true` } If `true`, the server certificate is verified against the supplied list of CAs.

*Returns*

* { ftp.Client } A new client instance.

### list()

Lists current script connections.

*Returns*

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

## class ftp.Client

To create an FTP client, use [ftp.create(options)](#create-options).

### chmod(path, mode)

Changes file 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 file on the server.

*Arguments*

* `path` { String } File path.

### get(path)

Downloads data from the server.

*Arguments*

* `path` { String } File path.

*Returns*

* { Buffer } A buffer containing the file data.

### list(path)

Lists the contents of a remote directory.

*Arguments*

* `path` { String } The path to the directory. The default is the current working directory.

*Returns*

* { Object\[] } A list of directory contents.
  * `type` { String } Entry type:
    * `d`: directory
    * `-`: file
    * `l`: symlink
  * `name` { String } Entry name.
  * `size` { Number } Entry size in bytes.
  * `modifyTime` { date } Last modified date of the entry.
  * `rights` { Object } Entry access rights.
    * `username` { String } User access rights (rwx).
    * `group` { String } Group access rights (rwx).
    * `other` { String } Other access rights (rwx).
  * `owner` { String } Owner name or ID. 
  * `group` { String } Group name or ID.
  * `target` { String } Symlink target.
  * `sticky` { Boolean } `True` if sticky bit is set.

### mkdir(path)

Creates a new directory on the server.

*Arguments*

* `path` { String } The directory to create.
* `recursive` { Boolean = *false* } Creates intermediate directories as required.

### put(path, data)

Uploads data to the server.

*Arguments*

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

### rename(oldPath, newPath)

Renames a file on the server.

*Arguments*

* `oldPath` { String } Old file name.
* `newPath` { String } New file name.

## Example

```javascript
const ftp = require('ftp'),

    conn = ftp.create({
        host: '<hostname>',
        port: '<port>',
        username: '<username>',
        password: '<password>',
        secureOptions: {
            rejectUnauthorized: false,
            ciphers: 'TLS_AES_256_GCM_SHA384',
            minVersion: 'TLSv1.3'
        }
    }),
    buffer = new Buffer('ftp works!')

conn.mkdir('/one/two', true)
conn.put('one/two/test.txt', buffer)
let list = conn.list('/one/two')

conn.close()

return list
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/ftp.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.