cpy-cli

cpy-cli is a command-line interface for copying files and directories with advanced features including glob pattern support, stream-based processing for performance, graceful filesystem handling, and flexible options for controlling copy behavior.

Package Information

• Package Name: cpy-cli
• Package Type: npm
• Language: JavaScript (ES modules)
• Installation: npm install --global cpy-cli
• Node.js Requirement: >=20

Core Command

cpy <source ...> <destination>

Basic Usage

# Copy a single file
cpy source.txt dest/

# Copy files with glob patterns
cpy 'src/*.png' dist/

# Copy with exclusion patterns
cpy 'src/*.png' '!src/goat.png' dist/

# Copy all files preserving directory structure
cpy . '../dist/' --cwd=src

# Copy with file renaming using templates
cpy 'src/*.png' dist --rename=hi-{{basename}}

Architecture

cpy-cli is built as a command-line wrapper around the programmatic cpy library. Key architectural components:

• CLI Interface: Uses meow library for argument parsing and help text generation
• Core Copy Engine: Delegates all file operations to the cpy library (v12.0.0+)
• Stream Processing: Inherits stream-based copying for performance from underlying cpy library
• Graceful Filesystem: Benefits from graceful-fs resilience through cpy dependency
• Template Engine: Custom template processing for {{basename}} placeholder in rename operations

The CLI acts as a thin interface layer, providing user-friendly options that map directly to cpy library parameters.

Capabilities

File and Directory Copying

Primary command for copying files and directories with advanced pattern matching and processing options.

cpy <source ...> <destination> [options]

Parameters:

• <source ...> - One or more source file paths or glob patterns. Supports negation patterns with ! prefix
• <destination> - Target directory path where files will be copied

Overwrite Control

Control whether existing files at the destination should be overwritten.

--no-overwrite

By default, cpy-cli will overwrite existing files. Use --no-overwrite to prevent overwriting and throw an error when a destination file already exists.

Usage Example:

# Prevent overwriting existing files
cpy source.txt dest --no-overwrite

Working Directory Specification

Specify the working directory for source file operations.

--cwd=<directory>

Parameters:

• <directory> - Path to the working directory (defaults to current working directory)

Usage Example:

# Copy files relative to a specific directory
cpy '*.js' ../output --cwd=src

File Renaming with Templates

Rename all source files using a template pattern with placeholder substitution.

--rename=<filename>

Parameters:

• <filename> - Target filename pattern supporting {{basename}} template placeholder

The {{basename}} placeholder gets replaced with the original filename without extension. The original file extension is preserved automatically.

Usage Examples:

# Rename all files to a fixed name
cpy 'src/*.png' dist --rename=logo.png

# Add prefix using basename template
cpy 'src/*.png' dist --rename=hi-{{basename}}

# Multiple placeholders supported
cpy 'src/*.png' dist --rename={{basename}}-copy-{{basename}}

Dotfile Handling

Control whether patterns match files that begin with a period (hidden files).

--dot

By default, glob patterns do not match dotfiles. Use --dot to include hidden files in pattern matching.

Usage Example:

# Include hidden files in copy operation
cpy '**/*' dest --dot

Directory Structure Flattening

Flatten the directory structure, placing all copied files in the same destination directory.

--flat

Usage Example:

# Copy all .js files to dest/ without preserving directory structure
cpy '**/*.js' dest --flat

Concurrency Control

Control the number of files being copied concurrently for performance optimization.

--concurrency=<number>

Parameters:

• <number> - Number of concurrent file operations (defaults to CPU cores × 2)

Usage Example:

# Limit concurrent operations
cpy 'src/**/*' dest --concurrency=4

Pattern Support

Glob Patterns

Source arguments support glob patterns for flexible file selection:

• * - Match any filename
• ** - Match any directory path recursively
• ? - Match any single character
• [abc] - Match any character in brackets
• {foo,bar} - Match any string in braces

Examples:

# All PNG files in src directory
cpy 'src/*.png' dist

# All files recursively
cpy 'src/**/*' dist

# Specific file extensions
cpy 'src/**/*.{js,ts}' dist

Negation Patterns

Use ! prefix to exclude files from selection:

# Copy all PNG files except goat.png
cpy 'src/*.png' '!src/goat.png' dist

# Copy all JS files except test files
cpy 'src/**/*.js' '!src/**/*.test.js' dist

Error Handling

The command handles errors gracefully and provides clear error messages:

• Missing operands: Error when source or destination is not provided
• Nonexistent source: Error when source files don't exist
• Overwrite protection: Error when --no-overwrite is used and destination file exists
• CpyError: Specific error handling for file operation failures

Exit codes:

• 0 - Success
• 1 - Error occurred

Advanced Usage Examples

Complex Pattern Matching

# Copy specific file types from multiple directories
cpy 'src/**/*.{png,jpg,gif}' 'assets/**/*.svg' dist/images

# Copy with multiple exclusions
cpy 'src/**/*' '!src/node_modules/**' '!src/.git/**' '!src/**/*.test.*' backup/

Directory Structure Management

# Preserve structure with specific working directory
cpy '**/*.md' ../docs --cwd=src

# Flatten deeply nested files
cpy 'src/**/*.config.{js,json}' config/ --flat

# Copy entire directory structure
cpy 'src/**/*' dist --cwd=src

File Renaming Strategies

# Add timestamp prefix (using basename)
cpy '*.log' archive/ --rename=2024-01-01-{{basename}}

# Convert to different naming convention
cpy 'src/*.component.ts' dist/ --rename={{basename}}.comp

Performance Optimization

# High concurrency for many small files
cpy 'assets/**/*.png' dist/ --concurrency=16

# Lower concurrency for large files
cpy '*.iso' backup/ --concurrency=2