or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

connection-management.mddirectory-operations.mdfile-management.mdfile-operations.mdfilesystem-info.mdindex.mdstream-operations.md
tile.json

tessl/npm-ssh2-sftp-client

Promise-based SFTP client for Node.js that wraps the ssh2 module

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ssh2-sftp-client@12.0.x

To install, run

npx @tessl/cli install tessl/npm-ssh2-sftp-client@12.0.0

index.mddocs/

SSH2 SFTP Client

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.

Package Information

  • Package Name: ssh2-sftp-client
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install ssh2-sftp-client

Core Imports

const SftpClient = require('ssh2-sftp-client');

For ES modules (if using Node.js with ES modules enabled):

import SftpClient from 'ssh2-sftp-client';

Basic Usage

const SftpClient = require('ssh2-sftp-client');

async function example() {
  const sftp = new SftpClient();
  
  try {
    await sftp.connect({
      host: 'example.com',
      username: 'user',
      password: 'password'
    });
    
    // List directory contents
    const files = await sftp.list('/remote/path');
    console.log(files);
    
    // Upload a file
    await sftp.put('/local/file.txt', '/remote/file.txt');
    
    // Download a file
    await sftp.get('/remote/file.txt', '/local/downloaded.txt');
    
  } catch (err) {
    console.error(err);
  } finally {
    await sftp.end();
  }
}

Architecture

SSH2 SFTP Client is built around several key components:

  • SftpClient Class: Main client class providing all SFTP operations
  • Connection Management: Promise-based connection handling with comprehensive error management
  • Event System: Built-in event listeners for connection lifecycle management
  • Streaming Support: Read/write stream creation for efficient large file handling
  • Bulk Operations: Concurrent transfer support for directory operations
  • Error Handling: Custom error codes and comprehensive exception management

Capabilities

Connection Management

Establishes and manages SFTP connections with comprehensive configuration options and authentication methods.

class SftpClient {
  constructor(clientName = 'sftp', callbacks = {});
  connect(config): Promise<Object>;
  end(): Promise<Boolean>;
}

Connection Management

File Operations

Core file transfer operations including upload, download, and streaming support for efficient data handling.

get(remotePath, dst, options, addListeners = true): Promise<String|Stream|Buffer>;
put(localSrc, remotePath, options): Promise<String>;
fastGet(remotePath, localPath, options): Promise<String>;
fastPut(localPath, remotePath, options): Promise<String>;
append(input, remotePath, options = {}): Promise<String>;

File Operations

Directory Operations

Directory management including listing, creation, deletion, and bulk transfer operations with filtering support.

list(remotePath, filter, addListeners = true): Promise<Array>;
mkdir(remotePath, recursive = false): Promise<String>;
rmdir(remoteDir, recursive = false): Promise<String>;
uploadDir(srcDir, dstDir, options): Promise<String>;
downloadDir(srcDir, dstDir, options = {}): Promise<String>;

Directory Operations

File System Information

File and directory information retrieval including existence checking, attribute inspection, and path resolution.

exists(remotePath): Promise<Boolean|String>;
stat(remotePath): Promise<Object>;
lstat(remotePath): Promise<Object>;
realPath(remotePath, addListeners = true): Promise<String>;
cwd(): Promise<String>;

File System Information

File Management

File management operations including deletion, renaming, permission changes, and remote copying.

delete(remotePath, notFoundOK = false, addListeners = true): Promise<String>;
rename(fPath, tPath, addListeners = true): Promise<String>;
posixRename(fPath, tPath, addListeners = true): Promise<String>;
chmod(rPath, mode, addListeners = true): Promise<String>;
rcopy(src, dst): Promise<String>;

File Management

Stream Operations

Low-level stream creation for direct read/write access to remote files with full client control over stream lifecycle.

createReadStream(remotePath, options): Object;
createWriteStream(remotePath, options): Object;

Stream Operations

Types

// Connection configuration
interface ConnectionConfig {
  host: string;
  port?: number;
  username: string;
  password?: string;
  privateKey?: string | Buffer;
  passphrase?: string;
  readyTimeout?: number;
  strictVendor?: boolean;
  debug?: Function;
  promiseLimit?: number;
}

// File listing entry
interface FileEntry {
  type: string;           // 'd' for directory, '-' for file, 'l' for link
  name: string;           // File/directory name
  size: number;           // Size in bytes
  modifyTime: number;     // Last modified time (milliseconds)
  accessTime: number;     // Last access time (milliseconds)
  rights: {
    user: string;         // User permissions (rwx format)
    group: string;        // Group permissions (rwx format)
    other: string;        // Other permissions (rwx format)
  };
  owner: number;          // Owner UID
  group: number;          // Group GID
  longname: string;       // Full listing format
}

// File attributes
interface FileStats {
  mode: number;           // File mode
  uid: number;            // Owner UID
  gid: number;            // Group GID
  size: number;           // Size in bytes
  accessTime: number;     // Last access time (milliseconds)
  modifyTime: number;     // Last modify time (milliseconds)
  isDirectory: boolean;   // Is directory
  isFile: boolean;        // Is regular file
  isBlockDevice: boolean; // Is block device
  isCharacterDevice: boolean; // Is character device
  isSymbolicLink: boolean; // Is symbolic link
  isFIFO: boolean;        // Is FIFO
  isSocket: boolean;      // Is socket
}

// Stream options
interface StreamOptions {
  flags?: string;         // File flags (r, w, a, etc.)
  encoding?: string;      // File encoding
  mode?: number;          // File mode
  autoClose?: boolean;    // Auto close stream
  start?: number;         // Start position
  end?: number;           // End position
}

// Transfer options
interface TransferOptions {
  readStreamOptions?: StreamOptions;
  writeStreamOptions?: StreamOptions;
  pipeOptions?: Object;
}

// Directory transfer options
interface DirectoryOptions {
  filter?: (filePath: string, isDirectory: boolean) => boolean;
  useFastput?: boolean;   // Use fastPut for uploads
  useFastget?: boolean;   // Use fastGet for downloads
}