node-run-cmd

1.0.1 · active · verified Tue Apr 21

node-run-cmd is a Node.js package designed to execute console or terminal commands programmatically. It supports both single and multiple commands, with options for sequential or parallel execution. The current stable version is 1.0.1, marking its initial public release. It offers robust control over command execution, including setting working directories, environment variables, detached mode, and callbacks for data, errors, and completion. It returns promises for asynchronous handling and also supports a callback style. Key differentiators include its detailed options object for fine-grained control over child processes and the ability to define different working directories for individual commands within an array. The package explicitly cautions against its use for cross-platform applications or when `node-fs-extra` can accomplish filesystem-related tasks more effectively, positioning itself as a solution for specific, platform-dependent command execution needs.

Common errors

```
Error: spawn <command> ENOENT
```
cause The command specified does not exist in the system's PATH, or the provided path to the executable is incorrect.

fix Verify that the command (`<command>`) is installed and available in the system's PATH. If not, provide the full absolute path to the executable or ensure it's installed globally or within `node_modules/.bin` if applicable.
```
Command failed to run with error: Error: Command failed: <command> ...
```
cause The executed shell command returned a non-zero exit code, indicating an error during its execution.

fix Inspect the `stderr` output (available via the `onError` callback or within the error object of the promise rejection) to diagnose the specific issue with the command. This often relates to incorrect arguments, file permissions, or environmental issues for the command itself.
```
TypeError: nrc.run is not a function
```
cause This error occurs when `nrc` is undefined or does not have a `run` method, typically due to an incorrect or missing `require('node-run-cmd')` statement.

fix Ensure that `const nrc = require('node-run-cmd');` is correctly placed and executed before attempting to call `nrc.run(...)`. Verify the package is installed in `node_modules`.

Warnings

gotcha The package explicitly warns against using it for applications requiring cross-platform compatibility, as shell commands are inherently platform-specific.
Fix: If cross-platform compatibility is a requirement, consider using platform-agnostic Node.js APIs (e.g., `fs` module) or libraries like `node-fs-extra` for file system operations, or abstracting commands based on `process.platform`.
gotcha It is not recommended for filesystem-related tasks if `node-fs-extra` can achieve the same result, as `node-fs-extra` provides a more robust and cross-platform compatible API.
Fix: For common file system operations (e.g., creating/deleting directories or files), prefer using `node-fs-extra` to leverage its native Node.js APIs and cross-platform reliability.
gotcha Incorrect handling of shell-specific syntax, quoting, or command paths can lead to unexpected behavior or failures.
Fix: Be meticulous about command string construction, especially with paths and arguments containing spaces or special characters. Use proper escaping (e.g., backticks, double quotes) according to the target shell. For robustness, consider passing command arguments as an array if the underlying `child_process` API allows.

Install

npm install node-run-cmd npm
yarn add node-run-cmd yarn
pnpm add node-run-cmd pnpm

Imports

nrc
wrong:
```
import { run } from 'node-run-cmd';
```
correct:
```
const nrc = require('node-run-cmd');
```
This package is primarily designed for CommonJS (`require`) usage in Node.js environments. While ESM import might work with specific loader configurations, the documented and intended usage is via `require`. The module exports a single object containing the `run` method.

Quickstart

Demonstrates installing the package, running multiple shell commands with options, and handling promise-based success and error states, including a basic cleanup.

const nrc = require('node-run-cmd');

// Run multiple commands sequentially, setting a specific working directory for one of them,
// and handle both successful completion and errors using promises.
nrc.run([
  'mkdir my-temp-dir',
  { command: 'echo "Hello, world!" > message.txt', cwd: 'my-temp-dir' },
  'ls my-temp-dir'
]).then(function(exitCodes) {
  console.log('All commands finished successfully with exit codes:', exitCodes);
  // Clean up
  return nrc.run('rm -rf my-temp-dir');
}).then(() => {
  console.log('Cleanup successful.');
}).catch(function(err) {
  console.error('One or more commands failed:', err);
  // Attempt cleanup even if a command failed
  nrc.run('rm -rf my-temp-dir').catch(cleanupErr => console.error('Cleanup also failed:', cleanupErr));
});

view raw JSON →