0
# SSH2 SFTP Client
1
2
SSH2 SFTP Client is a promise-based SFTP client for Node.js that wraps the SSH2 module, providing a high-level API for common SFTP operations. It supports comprehensive file and directory operations including upload, download, listing, creation and deletion, with advanced features like concurrent transfers via fastGet/fastPut methods, directory synchronization, streaming operations, and flexible authentication methods including SSH keys and agents.
3
4
## Package Information
5
6
- **Package Name**: ssh2-sftp-client
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install ssh2-sftp-client`
10
11
## Core Imports
12
13
```javascript
14
const SftpClient = require('ssh2-sftp-client');
15
```
16
17
For ES modules (if using Node.js with ES modules enabled):
18
19
```javascript
20
import SftpClient from 'ssh2-sftp-client';
21
```
22
23
## Basic Usage
24
25
```javascript
26
const SftpClient = require('ssh2-sftp-client');
27
28
async function example() {
29
const sftp = new SftpClient();
30
31
try {
32
await sftp.connect({
33
host: 'example.com',
34
username: 'user',
35
password: 'password'
36
});
37
38
// List directory contents
39
const files = await sftp.list('/remote/path');
40
console.log(files);
41
42
// Upload a file
43
await sftp.put('/local/file.txt', '/remote/file.txt');
44
45
// Download a file
46
await sftp.get('/remote/file.txt', '/local/downloaded.txt');
47
48
} catch (err) {
49
console.error(err);
50
} finally {
51
await sftp.end();
52
}
53
}
54
```
55
56
## Architecture
57
58
SSH2 SFTP Client is built around several key components:
59
60
- **SftpClient Class**: Main client class providing all SFTP operations
61
- **Connection Management**: Promise-based connection handling with comprehensive error management
62
- **Event System**: Built-in event listeners for connection lifecycle management
63
- **Streaming Support**: Read/write stream creation for efficient large file handling
64
- **Bulk Operations**: Concurrent transfer support for directory operations
65
- **Error Handling**: Custom error codes and comprehensive exception management
66
67
## Capabilities
68
69
### Connection Management
70
71
Establishes and manages SFTP connections with comprehensive configuration options and authentication methods.
72
73
```javascript { .api }
74
class SftpClient {
75
constructor(clientName = 'sftp', callbacks = {});
76
connect(config): Promise<Object>;
77
end(): Promise<Boolean>;
78
}
79
```
80
81
[Connection Management](./connection-management.md)
82
83
### File Operations
84
85
Core file transfer operations including upload, download, and streaming support for efficient data handling.
86
87
```javascript { .api }
88
get(remotePath, dst, options, addListeners = true): Promise<String|Stream|Buffer>;
89
put(localSrc, remotePath, options): Promise<String>;
90
fastGet(remotePath, localPath, options): Promise<String>;
91
fastPut(localPath, remotePath, options): Promise<String>;
92
append(input, remotePath, options = {}): Promise<String>;
93
```
94
95
[File Operations](./file-operations.md)
96
97
### Directory Operations
98
99
Directory management including listing, creation, deletion, and bulk transfer operations with filtering support.
100
101
```javascript { .api }
102
list(remotePath, filter, addListeners = true): Promise<Array>;
103
mkdir(remotePath, recursive = false): Promise<String>;
104
rmdir(remoteDir, recursive = false): Promise<String>;
105
uploadDir(srcDir, dstDir, options): Promise<String>;
106
downloadDir(srcDir, dstDir, options = {}): Promise<String>;
107
```
108
109
[Directory Operations](./directory-operations.md)
110
111
### File System Information
112
113
File and directory information retrieval including existence checking, attribute inspection, and path resolution.
114
115
```javascript { .api }
116
exists(remotePath): Promise<Boolean|String>;
117
stat(remotePath): Promise<Object>;
118
lstat(remotePath): Promise<Object>;
119
realPath(remotePath, addListeners = true): Promise<String>;
120
cwd(): Promise<String>;
121
```
122
123
[File System Information](./filesystem-info.md)
124
125
### File Management
126
127
File management operations including deletion, renaming, permission changes, and remote copying.
128
129
```javascript { .api }
130
delete(remotePath, notFoundOK = false, addListeners = true): Promise<String>;
131
rename(fPath, tPath, addListeners = true): Promise<String>;
132
posixRename(fPath, tPath, addListeners = true): Promise<String>;
133
chmod(rPath, mode, addListeners = true): Promise<String>;
134
rcopy(src, dst): Promise<String>;
135
```
136
137
[File Management](./file-management.md)
138
139
### Stream Operations
140
141
Low-level stream creation for direct read/write access to remote files with full client control over stream lifecycle.
142
143
```javascript { .api }
144
createReadStream(remotePath, options): Object;
145
createWriteStream(remotePath, options): Object;
146
```
147
148
[Stream Operations](./stream-operations.md)
149
150
## Types
151
152
```javascript { .api }
153
// Connection configuration
154
interface ConnectionConfig {
155
host: string;
156
port?: number;
157
username: string;
158
password?: string;
159
privateKey?: string | Buffer;
160
passphrase?: string;
161
readyTimeout?: number;
162
strictVendor?: boolean;
163
debug?: Function;
164
promiseLimit?: number;
165
}
166
167
// File listing entry
168
interface FileEntry {
169
type: string; // 'd' for directory, '-' for file, 'l' for link
170
name: string; // File/directory name
171
size: number; // Size in bytes
172
modifyTime: number; // Last modified time (milliseconds)
173
accessTime: number; // Last access time (milliseconds)
174
rights: {
175
user: string; // User permissions (rwx format)
176
group: string; // Group permissions (rwx format)
177
other: string; // Other permissions (rwx format)
178
};
179
owner: number; // Owner UID
180
group: number; // Group GID
181
longname: string; // Full listing format
182
}
183
184
// File attributes
185
interface FileStats {
186
mode: number; // File mode
187
uid: number; // Owner UID
188
gid: number; // Group GID
189
size: number; // Size in bytes
190
accessTime: number; // Last access time (milliseconds)
191
modifyTime: number; // Last modify time (milliseconds)
192
isDirectory: boolean; // Is directory
193
isFile: boolean; // Is regular file
194
isBlockDevice: boolean; // Is block device
195
isCharacterDevice: boolean; // Is character device
196
isSymbolicLink: boolean; // Is symbolic link
197
isFIFO: boolean; // Is FIFO
198
isSocket: boolean; // Is socket
199
}
200
201
// Stream options
202
interface StreamOptions {
203
flags?: string; // File flags (r, w, a, etc.)
204
encoding?: string; // File encoding
205
mode?: number; // File mode
206
autoClose?: boolean; // Auto close stream
207
start?: number; // Start position
208
end?: number; // End position
209
}
210
211
// Transfer options
212
interface TransferOptions {
213
readStreamOptions?: StreamOptions;
214
writeStreamOptions?: StreamOptions;
215
pipeOptions?: Object;
216
}
217
218
// Directory transfer options
219
interface DirectoryOptions {
220
filter?: (filePath: string, isDirectory: boolean) => boolean;
221
useFastput?: boolean; // Use fastPut for uploads
222
useFastget?: boolean; // Use fastGet for downloads
223
}
224
```