{"id":13991585,"url":"https://github.com/mscdex/node-ftp","last_synced_at":"2025-05-14T05:10:34.531Z","repository":{"id":45239296,"uuid":"1589664","full_name":"mscdex/node-ftp","owner":"mscdex","description":"An FTP client module for node.js","archived":false,"fork":false,"pushed_at":"2021-03-25T14:25:36.000Z","size":661,"stargazers_count":1133,"open_issues_count":140,"forks_count":244,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-05-11T17:17:21.476Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mscdex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-04-08T23:04:05.000Z","updated_at":"2025-04-28T05:49:27.000Z","dependencies_parsed_at":"2022-08-12T11:50:47.655Z","dependency_job_id":null,"html_url":"https://github.com/mscdex/node-ftp","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscdex%2Fnode-ftp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscdex%2Fnode-ftp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscdex%2Fnode-ftp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mscdex%2Fnode-ftp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mscdex","download_url":"https://codeload.github.com/mscdex/node-ftp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076849,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-09T14:01:28.168Z","updated_at":"2025-05-14T05:10:34.502Z","avatar_url":"https://github.com/mscdex.png","language":"JavaScript","readme":"Description\n===========\n\nnode-ftp is an FTP client module for [node.js](http://nodejs.org/) that provides an asynchronous interface for communicating with an FTP server.\n\n\nRequirements\n============\n\n* [node.js](http://nodejs.org/) -- v0.8.0 or newer\n\n\nInstall\n=======\n\n    npm install ftp\n\n\nExamples\n========\n\n* Get a directory listing of the current (remote) working directory:\n\n```javascript\n  var Client = require('ftp');\n\n  var c = new Client();\n  c.on('ready', function() {\n    c.list(function(err, list) {\n      if (err) throw err;\n      console.dir(list);\n      c.end();\n    });\n  });\n  // connect to localhost:21 as anonymous\n  c.connect();\n```\n\n* Download remote file 'foo.txt' and save it to the local file system:\n\n```javascript\n  var Client = require('ftp');\n  var fs = require('fs');\n\n  var c = new Client();\n  c.on('ready', function() {\n    c.get('foo.txt', function(err, stream) {\n      if (err) throw err;\n      stream.once('close', function() { c.end(); });\n      stream.pipe(fs.createWriteStream('foo.local-copy.txt'));\n    });\n  });\n  // connect to localhost:21 as anonymous\n  c.connect();\n```\n\n* Upload local file 'foo.txt' to the server:\n\n```javascript\n  var Client = require('ftp');\n  var fs = require('fs');\n\n  var c = new Client();\n  c.on('ready', function() {\n    c.put('foo.txt', 'foo.remote-copy.txt', function(err) {\n      if (err) throw err;\n      c.end();\n    });\n  });\n  // connect to localhost:21 as anonymous\n  c.connect();\n```\n\n\nAPI\n===\n\nEvents\n------\n\n* **greeting**(\u003c _string_ \u003emsg) - Emitted after connection. `msg` is the text the server sent upon connection.\n\n* **ready**() - Emitted when connection and authentication were sucessful.\n\n* **close**(\u003c _boolean_ \u003ehadErr) - Emitted when the connection has fully closed.\n\n* **end**() - Emitted when the connection has ended.\n\n* **error**(\u003c _Error_ \u003eerr) - Emitted when an error occurs. In case of protocol-level errors, `err` contains a 'code' property that references the related 3-digit FTP response code.\n\n\nMethods\n-------\n\n**\\* Note: As with the 'error' event, any error objects passed to callbacks will have a 'code' property for protocol-level errors.**\n\n* **(constructor)**() - Creates and returns a new FTP client instance.\n\n* **connect**(\u003c _object_ \u003econfig) - _(void)_ - Connects to an FTP server. Valid config properties:\n\n    * host - _string_ - The hostname or IP address of the FTP server. **Default:** 'localhost'\n\n    * port - _integer_ - The port of the FTP server. **Default:** 21\n\n    * secure - _mixed_ - Set to true for both control and data connection encryption, 'control' for control connection encryption only, or 'implicit' for implicitly encrypted control connection (this mode is deprecated in modern times, but usually uses port 990) **Default:** false\n\n    * secureOptions - _object_ - Additional options to be passed to `tls.connect()`. **Default:** (none)\n\n    * user - _string_ - Username for authentication. **Default:** 'anonymous'\n\n    * password - _string_ - Password for authentication. **Default:** 'anonymous@'\n\n    * connTimeout - _integer_ - How long (in milliseconds) to wait for the control connection to be established. **Default:** 10000\n\n    * pasvTimeout - _integer_ - How long (in milliseconds) to wait for a PASV data connection to be established. **Default:** 10000\n\n    * keepalive - _integer_ - How often (in milliseconds) to send a 'dummy' (NOOP) command to keep the connection alive. **Default:** 10000\n\n* **end**() - _(void)_ - Closes the connection to the server after any/all enqueued commands have been executed.\n\n* **destroy**() - _(void)_ - Closes the connection to the server immediately.\n\n### Required \"standard\" commands (RFC 959)\n\n* **list**([\u003c _string_ \u003epath, ][\u003c _boolean_ \u003euseCompression, ]\u003c _function_ \u003ecallback) - _(void)_ - Retrieves the directory listing of `path`. `path` defaults to the current working directory. `useCompression` defaults to false. `callback` has 2 parameters: \u003c _Error_ \u003eerr, \u003c _array_ \u003elist. `list` is an array of objects with these properties:\n\n      * type - _string_ - A single character denoting the entry type: 'd' for directory, '-' for file (or 'l' for symlink on **\\*NIX only**).\n\n      * name - _string_ - The name of the entry.\n\n      * size - _string_ - The size of the entry in bytes.\n\n      * date - _Date_ - The last modified date of the entry.\n\n      * rights - _object_ - The various permissions for this entry **(*NIX only)**.\n\n          * user - _string_ - An empty string or any combination of 'r', 'w', 'x'.\n\n          * group - _string_ - An empty string or any combination of 'r', 'w', 'x'.\n\n          * other - _string_ - An empty string or any combination of 'r', 'w', 'x'.\n     \n      * owner - _string_ - The user name or ID that this entry belongs to **(*NIX only)**.\n\n      * group - _string_ - The group name or ID that this entry belongs to **(*NIX only)**.\n\n      * target - _string_ - For symlink entries, this is the symlink's target **(*NIX only)**.\n\n      * sticky - _boolean_ - True if the sticky bit is set for this entry **(*NIX only)**.\n\n* **get**(\u003c _string_ \u003epath, [\u003c _boolean_ \u003euseCompression, ]\u003c _function_ \u003ecallback) - _(void)_ - Retrieves a file at `path` from the server. `useCompression` defaults to false. `callback` has 2 parameters: \u003c _Error_ \u003eerr, \u003c _ReadableStream_ \u003efileStream.\n\n* **put**(\u003c _mixed_ \u003einput, \u003c _string_ \u003edestPath, [\u003c _boolean_ \u003euseCompression, ]\u003c _function_ \u003ecallback) - _(void)_ - Sends data to the server to be stored as `destPath`. `input` can be a ReadableStream, a Buffer, or a path to a local file. `useCompression` defaults to false. `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n* **append**(\u003c _mixed_ \u003einput, \u003c _string_ \u003edestPath, [\u003c _boolean_ \u003euseCompression, ]\u003c _function_ \u003ecallback) - _(void)_ - Same as **put()**, except if `destPath` already exists, it will be appended to instead of overwritten.\n\n* **rename**(\u003c _string_ \u003eoldPath, \u003c _string_ \u003enewPath, \u003c _function_ \u003ecallback) - _(void)_ - Renames `oldPath` to `newPath` on the server. `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n* **logout**(\u003c _function_ \u003ecallback) - _(void)_ - Logout the user from the server. `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n* **delete**(\u003c _string_ \u003epath, \u003c _function_ \u003ecallback) - _(void)_ - Deletes a file, `path`, on the server. `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n* **cwd**(\u003c _string_ \u003epath, \u003c _function_ \u003ecallback) - _(void)_ - Changes the current working directory to `path`. `callback` has 2 parameters: \u003c _Error_ \u003eerr, \u003c _string_ \u003ecurrentDir. Note: `currentDir` is only given if the server replies with the path in the response text.\n\n* **abort**(\u003c _function_ \u003ecallback) - _(void)_ - Aborts the current data transfer (e.g. from get(), put(), or list()). `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n* **site**(\u003c _string_ \u003ecommand, \u003c _function_ \u003ecallback) - _(void)_ - Sends `command` (e.g. 'CHMOD 755 foo', 'QUOTA') using SITE. `callback` has 3 parameters: \u003c _Error_ \u003eerr, \u003c _string \u003eresponseText, \u003c _integer_ \u003eresponseCode.\n\n* **status**(\u003c _function_ \u003ecallback) - _(void)_ - Retrieves human-readable information about the server's status. `callback` has 2 parameters: \u003c _Error_ \u003eerr, \u003c _string_ \u003estatus.\n\n* **ascii**(\u003c _function_ \u003ecallback) - _(void)_ - Sets the transfer data type to ASCII. `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n* **binary**(\u003c _function_ \u003ecallback) - _(void)_ - Sets the transfer data type to binary (default at time of connection). `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n### Optional \"standard\" commands (RFC 959)\n\n* **mkdir**(\u003c _string_ \u003epath, [\u003c _boolean_ \u003erecursive, ]\u003c _function_ \u003ecallback) - _(void)_ - Creates a new directory, `path`, on the server. `recursive` is for enabling a 'mkdir -p' algorithm and defaults to false. `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n* **rmdir**(\u003c _string_ \u003epath, [\u003c _boolean_ \u003erecursive, ]\u003c _function_ \u003ecallback) - _(void)_ - Removes a directory, `path`, on the server. If `recursive`, this call will delete the contents of the directory if it is not empty. `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n* **cdup**(\u003c _function_ \u003ecallback) - _(void)_ - Changes the working directory to the parent of the current directory. `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n\n* **pwd**(\u003c _function_ \u003ecallback) - _(void)_ - Retrieves the current working directory. `callback` has 2 parameters: \u003c _Error_ \u003eerr, \u003c _string_ \u003ecwd.\n\n* **system**(\u003c _function_ \u003ecallback) - _(void)_ - Retrieves the server's operating system. `callback` has 2 parameters: \u003c _Error_ \u003eerr, \u003c _string_ \u003eOS.\n\n* **listSafe**([\u003c _string_ \u003epath, ][\u003c _boolean_ \u003euseCompression, ]\u003c _function_ \u003ecallback) - _(void)_ - Similar to list(), except the directory is temporarily changed to `path` to retrieve the directory listing. This is useful for servers that do not handle characters like spaces and quotes in directory names well for the LIST command. This function is \"optional\" because it relies on pwd() being available.\n\n### Extended commands (RFC 3659)\n\n* **size**(\u003c _string_ \u003epath, \u003c _function_ \u003ecallback) - _(void)_ - Retrieves the size of `path`. `callback` has 2 parameters: \u003c _Error_ \u003eerr, \u003c _integer_ \u003enumBytes.\n\n* **lastMod**(\u003c _string_ \u003epath, \u003c _function_ \u003ecallback) - _(void)_ - Retrieves the last modified date and time for `path`. `callback` has 2 parameters: \u003c _Error_ \u003eerr, \u003c _Date_ \u003elastModified.\n\n* **restart**(\u003c _integer_ \u003ebyteOffset, \u003c _function_ \u003ecallback) - _(void)_ - Sets the file byte offset for the next file transfer action (get/put) to `byteOffset`. `callback` has 1 parameter: \u003c _Error_ \u003eerr.\n","funding_links":[],"categories":["JavaScript","Network"],"sub_categories":["FTP"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmscdex%2Fnode-ftp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmscdex%2Fnode-ftp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmscdex%2Fnode-ftp/lists"}