{"id":10624,"library":"chokidar-cli","title":"Chokidar CLI","description":"Chokidar CLI is an ultra-fast, cross-platform command-line utility designed to watch file system changes and execute arbitrary commands or stream event output. It is built upon the robust and widely adopted `chokidar` library, which is known for its battle-tested stability and efficient file watching across various operating systems, handling quirks of `fs.watch` and `fs.watchFile` by normalizing events and supporting atomic/chunked writes. Currently at version 3.0.0, this tool provides a simple interface for developers to integrate automated tasks, such as compilation or testing, directly into their workflow upon file modifications. While the underlying `chokidar` library has seen recent updates (v4 and v5 as of late 2024/2025), `chokidar-cli` itself has not had a major release since v3.0.0 in July 2021, suggesting a slower release cadence for the CLI wrapper. Its key differentiators lie in abstracting the complexities of file system event handling and providing a straightforward command-line interface for common automation needs without requiring programmatic setup.","status":"maintenance","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/open-npm-tools/chokidar-cli","tags":["javascript","fs","watch","watchFile","watcher","watching","file","fsevents","chokidar"],"install":[{"cmd":"npm install chokidar-cli","lang":"bash","label":"npm"},{"cmd":"yarn add chokidar-cli","lang":"bash","label":"yarn"},{"cmd":"pnpm add chokidar-cli","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core file watching library that chokidar-cli wraps and exposes via the command line.","package":"chokidar","optional":false}],"imports":[{"note":"This package is a command-line utility. Its functionality is accessed via the `chokidar` command in the terminal, not via programmatic JavaScript imports. Attempting to `import` or `require` this package directly will result in errors as it does not expose a public JavaScript API for direct consumption.","wrong":"import { chokidar } from 'chokidar-cli'","symbol":"chokidar","correct":"npm install -g chokidar-cli\n# Then use the 'chokidar' command in your terminal"},{"note":"When installed locally, the `chokidar` command is available via npm scripts or by using `npx chokidar`. Direct CommonJS/ESM import is not supported as it's a CLI wrapper. Ensure proper escaping of quotes within package.json scripts for cross-platform compatibility.","wrong":"const chokidar = require('chokidar-cli')","symbol":"chokidar","correct":"npm install chokidar-cli\n# Then use in package.json scripts:\n# {\"scripts\": {\"watch:js\": \"chokidar \\\"**/*.js\\\" -c \\\"npm run build-js\\\"\"}}"},{"note":"The command line utility is invoked as `chokidar`, not `chokidar-cli`. Using `chokidar-cli` as the command name will result in a 'command not found' error.","wrong":"chokidar-cli \"src/**/*.less\" -c \"npm run build-less -- {path}\"","symbol":"chokidar","correct":"chokidar \"src/**/*.less\" -c \"npm run build-less -- {path}\""}],"quickstart":{"code":"#!/bin/bash\n\n# Install chokidar-cli globally for easy command access\nnpm install -g chokidar-cli\n\n# Create a dummy project directory and a file\nmkdir -p my-watched-project/src\necho \"// Initial content\" > my-watched-project/src/app.js\n\n# Navigate into the project directory\ncd my-watched-project\n\necho \"Watching for changes in src/**/*.js. Try modifying src/app.js...\"\n\n# Run chokidar to watch JavaScript files and execute a simple echo command\n# The -c flag runs a command, and {event} and {path} are placeholders\nchokidar \"src/**/*.js\" -c \"echo 'File {path} was {event}ed!' && ls -la src\"\n\n# To stop watching, press Ctrl+C in the terminal where chokidar is running.\n\n# Example of how to trigger an event (run this in a separate terminal after starting chokidar):\n# echo \"console.log('updated content');\" >> src/app.js\n# rm src/app.js\n# echo \"// New file\" > src/another.js\n","lang":"bash","description":"Demonstrates global installation, watching a glob pattern for `.js` files, and executing a command with event and path details on changes."},"warnings":[{"fix":"Always use double quotes (e.g., `\"**/*.js\" -c \"your command here\"`) for patterns and commands. For commands within `package.json` scripts, escape inner double quotes: `\"chokidar \\\"**/*.js\\\" -c \\\"echo {event}\\\"`.","message":"When specifying patterns and commands, especially within `package.json` scripts, cross-platform compatibility requires the use of double quotes (escaped if necessary) around arguments. Single quotes may not be universally supported across all operating systems and shells, leading to parsing issues.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"After installation (`npm install -g chokidar-cli` or `npm install chokidar-cli`), always use the command `chokidar` to run the utility.","message":"The package name is `chokidar-cli`, but the command line utility itself is invoked as `chokidar` (without the `-cli` suffix). Using `chokidar-cli` on the command line will result in a 'command not found' error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Append `--polling` to your `chokidar` command when watching network-mounted directories: `chokidar \"**/*.less\" -c \"npm run build-less\" --polling`.","message":"Watching files on network directories (e.g., NFS, SMB shares) or within certain Docker environments often requires using the `--polling` option for reliable change detection, as native file system events may not propagate correctly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Monitor `chokidar-cli` release notes for updates regarding its internal `chokidar` dependency. For `chokidar` itself, ensure Node.js v20+ for v5, or v14+ for v4.","message":"The underlying `chokidar` library has moved to ESM-only and increased its minimum Node.js requirement to v20+ in its v5 release (Nov 2025). While `chokidar-cli` v3.0.0 only requires Node.js >=8.10.0, it uses an older version of `chokidar`. Compatibility with future `chokidar-cli` versions may require updated Node.js environments and changes if `chokidar-cli` itself updates to `chokidar` v4/v5.","severity":"deprecated","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `chokidar` instead of `chokidar-cli` in your terminal or scripts. Example: `chokidar \"./**/*.js\" -c \"echo File changed\"`.","cause":"The command line utility is named `chokidar`, not `chokidar-cli`, even though the npm package is `chokidar-cli`.","error":"command not found: chokidar-cli"},{"fix":"Increase your system's file descriptor limit (e.g., `ulimit -n 2048` on Linux/macOS for the current session, or modify system configuration for permanent changes). Alternatively, refine your glob patterns to watch fewer files and directories, or use `chokidar`'s `ignored` option to exclude unnecessary paths.","cause":"The operating system's limit for open file descriptors has been reached. This often happens when watching a very large number of files/directories, or when a tool that uses `chokidar` (like `chokidar-cli`) is misconfigured to watch too broadly.","error":"Error: EMFILE: too many open files, watch"},{"fix":"Ensure the command passed to `-c` is enclosed in double quotes. If the command itself contains double quotes (e.g., for string literals), escape them properly. Example for `package.json`: `\"watch:build\": \"chokidar \\\"src/**/*.ts\\\" -c \\\"npm run compile -- --path={path}\\\"\"`.","cause":"Incorrect quoting or shell interpretation of the command string, especially when it contains spaces, variables, or other special characters.","error":"Command not running or syntax error in command specified with -c"}],"ecosystem":"npm"}