Repository navigation
node-ssh 14 needs Node.js 22 or newer. It adds timeouts and AbortSignal support for commands, atomic uploads and skipping unchanged files, and fixes crashes and confusing errors around connection failures, large output and SFTP. The full list is in CHANGELOG.md.
Breaking changes
- Node.js 22 or newer is required.
execandexecCommandreject with the connection's error when the connection fails while a command runs. They used to resolve withcode: null. #132- With
cwd, the command no longer runs whencdfails, for example because the directory doesn't exist. The result has thecderror instderrand a non-zerocode. The command used to run in the remote user's home directory.
New
timeout,signalandkillSignaloptions forexecandexecCommand. When the timeout passes or theAbortSignalaborts, node-ssh asks the server to sendkillSignal(defaultTERM) to the command, closes its channel and rejects. #465await ssh.execCommand('./build.sh', { timeout: 5000 }) // rejects with an SSHError, code 'ETIMEDOUT'
noBufferoption forexecandexecCommand: output goes only toonStdoutandonStderr, for commands with large output. #474atomicoption forputFile,putFilesandputDirectory: each file is uploaded to a hidden temporary file and renamed into place once complete, so readers never see a partial file. #349skipUnchangedoption forputFile,putFilesandputDirectory: files whose remote copy has the same size and modification time are not uploaded again. #466config.privateKeyaccepts aBuffer. #446- A
cwdthat starts with~/is relative to the remote user's home directory. #443 - The README has new sections on interactive programs (vim, nano, interactive shells), answering prompts, and keyboard-interactive authentication.
Fixes
- Output that the server splits in the middle of a multi-byte UTF-8 character (or a base64 group) is no longer corrupted. #487
- Output too large to return as a string rejects with an
SSHError(ERR_OUTPUT_TOO_LARGE) instead of crashing the process. #474 - An
onStdout,onStderroronChannelcallback that throws rejects that command and closes only its channel, instead of closing the connection. #257 - An error on an idle connection, such as
ECONNRESETor a keepalive timeout, no longer crashes the process. #132 dispose()waits up to 2 seconds for SFTP close replies, so a read stream disposed onendno longer fails withNo response from server. #471- More than 10 operations at once on one connection no longer print
MaxListenersExceededWarning. isConnected()isfalseuntil the connection is ready and right afterconnect()fails. #459- Clearer errors for
putFileonto a directory (#312) and for SFTP sessions that fail to start (#414, #440). - Requests no longer wait about 40 ms per round trip on Node.js 26 (
TCP_NODELAYis set).
TypeScript and packaging
- The declarations no longer need
esModuleInteroporallowSyntheticDefaultImports. #444 - ESM projects get ESM declarations (
lib/index.d.mts), CommonJS projects getlib/index.d.ts. import NodeSSH from 'node-ssh'is now a TypeScript error everywhere; it used to compile in CommonJS projects and crash at runtime. Useimport { NodeSSH } from 'node-ssh'.@types/ssh2is an optional peer dependency (^1.11.2). TypeScript projects install it themselves.- The build output moved to
lib/index.js,lib/index.mjs,lib/index.d.tsandlib/index.d.mts. Importingnode-sshworks as before; deep imports of the oldlib/cjs,lib/esmorlib/typingspaths no longer resolve. ssh2is now^1.17.0.is-streamandmake-dirare no longer dependencies.