foreach-cli: Execute Command Per File

1.8.1 verified Thu Apr 23 auth: no javascript

foreach-cli is a command-line utility designed to execute a specified shell command for each file that matches a given glob pattern. Currently at version 1.8.1, the package provides a stable and reliable method for batch processing files. It differentiates itself from its predecessor, `each-cli`, by consistently setting the current working directory (CWD) to where `foreach-cli` was invoked, rather than changing it to the matched file's directory. This design choice simplifies command construction and prevents unexpected path issues. Additionally, it accepts command arguments as direct strings, enabling complex shell commands, including piping and redirects, that might be problematic with other tools. The utility supports various placeholders like `#{path}`, `#{dir}`, and `#{name}` to dynamically inject file-specific information into the executed commands.

Common errors

error foreach: command not found ↓

cause The `foreach` executable is not in your system's PATH.

fix

Install the package globally (npm install -g foreach-cli) or use npx foreach-cli ... to execute it without global installation.

error Error: Command failed: <your command> ↓

cause The command executed by `foreach-cli` (specified with `-x`) failed. This error is typically a pass-through from the underlying shell command.

fix

Check the command you passed to -x (e.g., tar xvf #{path}). Run it manually on a single file to debug syntax errors, incorrect paths, or missing binaries. Ensure necessary tools are installed and in the PATH for foreach-cli's environment.

error No files found matching glob: <your glob> ↓

cause The provided glob pattern (`-g`) did not match any files in the current working directory or its subdirectories.

fix

Verify your glob pattern syntax. Ensure you are running foreach-cli from the correct directory where the files reside. Use an absolute glob path if needed, or check for typos in file extensions/names.

Warnings

breaking This package is a complete rewrite of `each-cli`. The most significant breaking change is how the current working directory (CWD) is handled. `foreach-cli` maintains the CWD of the original invocation, whereas `each-cli` changed the CWD to the directory of each matched file. This requires updating commands that rely on relative paths. ↓

fix Review all commands, especially those using relative paths, to ensure they correctly reference files given the consistent CWD. Use explicit placeholders like `#{path}` or `#{dir}` where ambiguity might arise.

gotcha When executing complex commands with pipes or special characters, ensure the entire command passed to `-x` is properly quoted. Without quoting, the shell might interpret parts of your command as arguments to `foreach-cli` itself. ↓

fix Always enclose the command argument for `-x` within double quotes (e.g., `-x "command | another_command"`) to ensure it's treated as a single string.

gotcha The primary use case for `foreach-cli` is command-line execution. While there's a programmatic `Cli` class export, its API is undocumented and not intended for general programmatic consumption. Relying on it may lead to unstable behavior across versions. ↓

fix Prefer using `foreach-cli` directly from the shell or via `child_process.exec`/`child_process.spawn` if integrating into a Node.js script. Do not directly import the `Cli` class for application logic unless you are prepared for potential internal API changes.

Install

npm install foreach-cli

yarn add foreach-cli

pnpm add foreach-cli

Imports

foreachCli
wrong
```
const foreachCli = require('foreach-cli');
```
correct
```
import { Cli } from 'foreach-cli'; // for programmatic usage, typically not required
```
While the `index.js` exports a `Cli` class, `foreach-cli` is primarily a command-line utility. Direct programmatic import and usage are uncommon and undocumented; most users interact with it via the shell. The internal API is not stable for general consumption.

Quickstart

Demonstrates installation and basic command-line usage to process files matching glob patterns.

npm install foreach-cli

# Create some dummy files
echo "content A" > folder1/fileA.txt
echo "content B" > folder2/fileB.log
echo "content C" > folder1/fileC.js

# Example 1: Count lines in all .txt files
# This command will execute 'wc -l' for each .txt file in the current directory or subdirectories.
# The #{path} placeholder is replaced with the full path to the matched file.
foreach -g "**/*.txt" -x "echo 'Processing #{path}:'; wc -l #{path}"

# Example 2: Rename all .log files to .oldlog
# This demonstrates using multiple placeholders and shell commands for file manipulation.
foreach -g "**/*.log" -x "echo 'Renaming #{path} to #{dir}/#{name}.oldlog'; mv #{path} #{dir}/#{name}.oldlog"

# Verify the renaming
ls -R