Recursive Copy CLI Tool

1.0.20 verified Thu Apr 23 auth: no javascript maintenance

This package provides a command-line interface (CLI) for the `recursive-copy` library, enabling robust and flexible file and directory copying operations directly from the terminal. As of April 2026, the current stable version is `1.0.20`, released in August 2021. The release cadence appears to be infrequent, primarily driven by dependency updates rather than new feature development, suggesting a stable but largely maintained project. Key differentiators of `recursive-copy-cli` include its support for advanced copying scenarios: filtering files using glob patterns or regular expressions, transforming file contents via external JavaScript modules, and renaming files based on custom patterns or logic provided by modules. It provides fine-grained control over recursive copying, offering options for overwriting existing files, expanding symbolic links, and explicitly including or excluding dotfiles and OS-specific junk files (e.g., `.DS_Store`, `Thumbs.db`), which distinguishes it from simpler `cp` commands by offering a programmatic and configurable approach to file synchronization and preparation tasks.

Common errors

error command not found: recursive-copy ↓

cause The `recursive-copy-cli` package was not installed globally, or the global `node_modules` bin directory is not in your system's PATH.

fix

Install the package globally using npm install -g recursive-copy-cli. If the issue persists, verify your system's PATH configuration to ensure npm's global bin directory is included.

error Error: Cannot find module 'through2' (or similar for other modules) ↓

cause An external transformation or renaming module relies on a dependency (like 'through2') that is not installed in the context where the CLI is running or where the module is located.

fix

Ensure that any external modules specified with --transform-module or --rename-module have their own dependencies correctly installed (e.g., by running npm install in the directory of the external module) or are self-contained.

error Error: Unknown argument: --some-unrecognized-option ↓

cause You are attempting to use a command-line option that is not supported by `recursive-copy-cli` or has a typo.

fix

Review the available options by running recursive-copy --help. Correct any typos or remove unsupported arguments.

Warnings

gotcha The package has not seen active development or new feature releases since August 2021. Its core dependencies, including `recursive-copy` and `yargs`, have received security updates in the interim. Using an older version might expose projects to known vulnerabilities. ↓

fix While no new versions are available for this CLI, ensure your project's `npm` dependencies are regularly audited (`npm audit`). Consider using the underlying `recursive-copy` library directly if more up-to-date functionality or direct control is needed, or if security concerns arise.

gotcha The `engines.node` field specifies `>=10.19.0`, which is a very old Node.js version. While the CLI might still function on newer Node.js runtimes (e.g., Node 18, 20), compatibility issues with underlying dependencies or new language features are not explicitly tested or guaranteed. Newer Node.js versions might exhibit unexpected behavior or performance regressions. ↓

fix Test the CLI thoroughly in your target Node.js environment. If issues arise, consider isolating its usage to a container with a compatible Node.js version or exploring alternatives for recursive copying in modern Node.js environments.

gotcha The `--filter`, `--transform-module`, and `--rename-module` options expect specific formats (glob/regex for filter, file paths for modules). Incorrect syntax or non-existent paths for module arguments will lead to silent failures or errors during execution, as the CLI will not be able to load or apply them. ↓

fix Always ensure paths to transformation/renaming modules are correct and accessible from the execution directory. For `--filter`, use valid glob patterns or regular expressions. Debug with `--debug` flag to see more verbose output.

Install

npm install recursive-copy-cli

yarn add recursive-copy-cli

pnpm add recursive-copy-cli

Imports

recursive-copy
wrong
```
import { recursiveCopy } from 'recursive-copy-cli'
```
correct
```
npm install -g recursive-copy-cli
```
This package is a command-line interface (CLI) tool and is not intended for direct JavaScript/TypeScript import. It should be installed globally and executed from the terminal.
Transformation Module
wrong
```
recursive-copy src dest --transform-module { myTransformFunction }
```
correct
```
recursive-copy src dest --transform-module ./my-transform-module.js
```
Transformation modules must be external JavaScript files that export a function returning a transform stream. The module path is provided as a CLI argument, not the function itself or inline code.
Renaming Module
wrong
```
recursive-copy src dest --rename-module myRenameFunction
```
correct
```
recursive-copy src dest --rename-module ./my-rename-module.js
```
Similar to transformation modules, renaming functionality requires an external JavaScript file exporting a function that dictates the new path based on the original. Ensure the path is correct.

Quickstart

Demonstrates global installation and basic usage, including copying with options and a simple content transformation using an external module.

npm install -g recursive-copy-cli

mkdir source-files
echo "Hello World" > source-files/test.txt
echo "hidden file" > source-files/.gitignore

# Basic copy, excluding dotfiles
recursive-copy source-files destination-folder

# Copying with dotfiles and overwriting
recursive-copy source-files destination-folder --dot --overwrite

# Example with transformation: converts content to uppercase
echo "module.exports = (path) => require('through2')((chunk, enc, cb) => { cb(null, chunk.toString().toUpperCase()); });" > uppercase-transform.js
recursive-copy source-files destination-folder --transform-module ./uppercase-transform.js --overwrite

cat destination-folder/test.txt # Should output 'HELLO WORLD'