Chokidar CLI

Chokidar CLI is an ultra-fast cross-platform command line utility for watching file system changes. It provides comprehensive file watching capabilities with configurable options for command execution, debouncing, throttling, and cross-platform compatibility. Built on top of the battle-tested chokidar library, it enables developers to monitor file modifications, additions, and deletions through glob patterns with support for executing custom commands when changes occur.

Package Information

• Package Name: chokidar-cli
• Package Type: npm
• Language: JavaScript
• Installation: npm install chokidar-cli (locally) or npm install -g chokidar-cli (globally)
• Node.js Requirement: >= 8.10.0

Core Imports

For programmatic usage of the utils module:

const { run } = require("chokidar-cli/utils");

Basic Usage

Command Line Interface

# Watch JavaScript files and run build command
chokidar "**/*.js" -c "npm run build-js"

# Watch multiple file types
chokidar "**/*.js" "**/*.less"

# Watch with polling (for network directories)
chokidar "**/*.less" -c "npm run build-less" --polling

# Use path and event variables in commands
chokidar "**/*.less" -c "if [ '{event}' = 'change' ]; then npm run build-less -- {path}; fi;"

Programmatic Usage

const { run } = require("chokidar-cli/utils");

// Execute a cross-platform command
run("npm test")
  .then(exitCode => {
    console.log(`Command completed with exit code: ${exitCode}`);
  })
  .catch(error => {
    console.error("Command failed:", error);
  });

// Execute with options
run("ls -la", {
  cwd: "/some/directory",
  pipe: false,
  callback: (child) => {
    console.log(`Started process with PID: ${child.pid}`);
  }
})
  .then(exitCode => console.log("Done"))
  .catch(console.error);

Capabilities

Command Line Interface

The primary interface for chokidar-cli is its command line utility.

chokidar <pattern> [<pattern>...] [options]

Parameters:

• <pattern> - Glob pattern(s) to specify files to be watched. Multiple patterns can be separated by spaces.

Options:

• -c, --command <string> - Command to run after each change. Supports {path} and {event} placeholders
• -d, --debounce <number> - Debounce timeout in ms for executing command (default: 400)
• -t, --throttle <number> - Throttle timeout in ms for executing command (default: 0)
• -s, --follow-symlinks - Follow symbolic links instead of watching symlinks themselves (default: false)
• -i, --ignore <string> - Pattern for files to ignore. Supports glob patterns or regex format: /pattern/flags
• --initial - Run command initially once before watching (default: false)
• -p, --polling - Use fs.watchFile (polling) instead of fs.watch (default: false)
• --poll-interval <number> - Polling interval in ms when --polling is set (default: 100)
• --poll-interval-binary <number> - Binary file polling interval in ms when --polling is set (default: 300)
• --verbose - Verbose and human-readable output (default: false)
• --silent - Suppress internal chokidar-cli messages (default: false)
• -h, --help - Show help
• -v, --version - Show version information

Cross-Platform Command Execution

Utility function for executing shell commands in a cross-platform manner.

/**
 * Execute a shell command in a cross-platform manner
 * @param {string} cmd - The command to execute
 * @param {Object} [opts] - Configuration options
 * @param {boolean} [opts.pipe=true] - Whether to pipe stdio to parent process
 * @param {string} [opts.cwd] - Working directory for command execution
 * @param {Function} [opts.callback] - Callback function called after successful spawn
 * @returns {Promise<number>} Promise that resolves with exit code or rejects with error
 */
function run(cmd, opts);

The run function automatically resolves the appropriate shell:

• Windows: Uses COMSPEC environment variable with /c flag
• Unix-like systems: Uses SHELL environment variable with -c flag

Event Types

Chokidar CLI monitors and reports the following file system events:

// Event types reported in output
type FileEvent = 'add' | 'addDir' | 'unlink' | 'unlinkDir' | 'change';

Event Descriptions:

• add - File added
• addDir - Directory added
• unlink - File removed
• unlinkDir - Directory removed
• change - File changed

Output Formats

Default Output

Events are streamed to stdout in the format event:path:

change:src/app.js
add:src/components/Button.js
unlink:src/old-file.js

Verbose Output

Human-readable event descriptions with file paths:

File changed: src/app.js
File added: src/components/Button.js
File removed: src/old-file.js

Silent Mode

No output except for errors and the initial "Watching..." message.

Configuration Options

Default Configuration

interface DefaultOptions {
  debounce: 400;           // ms
  throttle: 0;             // ms
  followSymlinks: false;
  ignore: null;
  polling: false;
  pollInterval: 100;       // ms
  pollIntervalBinary: 300; // ms
  verbose: false;
  silent: false;
  initial: false;
  command: null;
}

Ignore Patterns

The --ignore option supports:

• Glob patterns: "**/node_modules/**"
• Regex format: "/\\.git/i" (case-insensitive regex matching .git)

Multiple ignore patterns can be specified by using the option multiple times.

Command Placeholders

When using the --command option, the following placeholders are replaced:

• {path} - Replaced with the file path that triggered the event
• {event} - Replaced with the event type (add, change, unlink, etc.)

Error Handling

Common Errors

• Shell Resolution Error: Thrown when neither SHELL nor COMSPEC environment variables are set (error message: "$SHELL environment variable is not set.")
• Command Execution Errors: Logged with full stack traces when commands fail
• File Watching Errors: Chokidar errors are logged with stack traces

Error Output

All errors are written to stderr with descriptive messages and stack traces for debugging.

Cross-Platform Compatibility

Chokidar CLI automatically handles cross-platform differences:

• Shell Resolution: Automatically detects Windows (COMSPEC) vs Unix (SHELL) environments
• Command Execution: Uses appropriate shell flags (/c for Windows, -c for Unix)
• File Watching: Leverages chokidar's cross-platform file watching capabilities
• Polling Mode: Available for network directories and non-standard file systems

Dependencies

• chokidar: Core file watching functionality
• yargs: Command line argument parsing
• lodash.debounce: Command execution debouncing
• lodash.throttle: Command execution throttling