{"id":17058,"library":"rsync","title":"Rsync CLI Wrapper","description":"node-rsync is a Node.js library that provides a programmatic interface for building and executing `rsync` commands. It functions as a wrapper around the system's `rsync` utility, allowing developers to construct complex synchronization commands using a fluent API in JavaScript or TypeScript applications. The current stable version is 0.6.1. Releases are infrequent, typically addressing specific bugs or adding minor enhancements (such as Windows path support), rather than following a strict cadence. Its primary utility lies in automating file synchronization, backup tasks, and deployments within Node.js environments by abstracting the command-line intricacies of `rsync` into a more manageable, object-oriented structure.","status":"active","version":"0.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/mattijs/node-rsync","tags":["javascript","rsync","wrapper","cli","command"],"install":[{"cmd":"npm install rsync","lang":"bash","label":"npm"},{"cmd":"yarn add rsync","lang":"bash","label":"yarn"},{"cmd":"pnpm add rsync","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is primarily a CommonJS module. This is the canonical and most reliable import method for Node.js environments.","symbol":"Rsync","correct":"const Rsync = require('rsync');"},{"note":"When used in an ESM environment, bundlers (like Webpack, Rollup) or Node.js's built-in CJS-ESM interop will typically treat the `Rsync` class as the default export of the module.","symbol":"Rsync","correct":"import Rsync from 'rsync';"},{"note":"Attempting a named import (`import { Rsync }`) for this CommonJS package's single export will typically result in `undefined` for `Rsync`, as it's not explicitly exported as a named member. Use the default import syntax instead.","wrong":"import { Rsync } from 'rsync';","symbol":"Rsync","correct":"import Rsync from 'rsync';"}],"quickstart":{"code":"const Rsync = require('rsync');\n\n// 1. Build the rsync command configuration\nconst rsync = new Rsync()\n  .shell('ssh')                 // Use SSH for remote connections\n  .flags('az')                 // 'a' for archive mode, 'z' for compress\n  .source('/path/to/local/source/') // Local directory to synchronize from\n  .destination('user@remote.server:/path/to/remote/destination/'); // Remote destination\n\n// 2. Execute the command and handle results\nrsync.execute(function(error, code, cmd) {\n    if (error) {\n        console.error('Rsync command failed:', error.message);\n        console.error('Exit Code:', code);\n        console.error('Executed Command:', cmd);\n        // Depending on `code`, you might want to retry or log specific errors\n    } else {\n        console.log('Rsync command completed successfully.');\n        console.log('Executed Command:', cmd);\n        // Further processing after successful synchronization\n    }\n});\n","lang":"javascript","description":"Demonstrates how to initialize an Rsync instance, configure a basic remote synchronization command using SSH, common flags (archive, compress), and then execute it with error handling."},"warnings":[{"fix":"Ensure `rsync` is installed on your operating system. For Linux (Debian/Ubuntu): `sudo apt-get install rsync`; for macOS: `brew install rsync`; for Windows: utilize WSL, Cygwin, or a similar environment with `rsync`.","message":"This library acts as a wrapper for the system's `rsync` command-line utility. The `rsync` binary must be pre-installed and available in the system's PATH for this package to function. The Node.js package does not bundle the `rsync` executable itself.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always consult the official `rsync` man page (`man rsync`) or documentation for correct options and syntax. Test complex `rsync` commands directly on the command line before integrating them into `node-rsync`.","message":"The `.set(option, value)` method and other configuration methods (like `.flags()`) do not validate options or arguments against the official `rsync` manual. Providing incorrect options, malformed values, or values for valueless flags can lead to silent `rsync` failures (exit code 1, 23, etc.) that are only discoverable during execution.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to `node-rsync` version 0.6.1 or newer, which includes explicit support for Windows file paths under Cygwin. If upgrading isn't possible, ensure all paths are strictly POSIX-style (e.g., `/cygdrive/c/path`) and avoid native Windows path separators.","message":"Older versions of `node-rsync` (prior to 0.6.1) had known issues with handling Windows file paths, particularly when running `rsync` through environments like Cygwin. This could lead to incorrect path resolution, 'No such file or directory' errors, or failed synchronizations.","severity":"breaking","affected_versions":"<0.6.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install the `rsync` utility on your system. For example, `sudo apt-get install rsync` (Linux), `brew install rsync` (macOS), or ensure it's available in your chosen Windows environment (e.g., WSL, Cygwin).","cause":"The operating system cannot find the `rsync` executable. This typically means `rsync` is not installed or not in the system's PATH.","error":"Error: spawn rsync ENOENT"},{"fix":"Call `rsync.command()` to inspect the full `rsync` command string. Execute this string manually in your terminal to debug the `rsync` error directly, then adjust your `node-rsync` builder calls accordingly.","cause":"The `rsync` command generated by `node-rsync` contains an invalid option, flag, or argument combination. This often occurs due to a typo or misunderstanding of `rsync`'s command-line syntax when using `.set()` or `.flags()`.","error":"rsync error: syntax or usage error (code 1) at main.c(XXX) [client=X.X.X]"},{"fix":"Verify that both your source and destination paths are correct, exist, and have appropriate read/write permissions for the user executing the `node-rsync` process. For Windows, ensure paths are correctly formatted (e.g., using `/` instead of `\\` or correctly mapping Cygwin paths).","cause":"One of the specified source or destination paths does not exist or is inaccessible to the user running the `rsync` command. This can also happen with incorrect path formats, especially on Windows.","error":"rsync: [sender] failed to open ...: No such file or directory (2)"}],"ecosystem":"npm","meta_description":null}