API reference

run(command, options?, callback?)

Starts command through the platform shell using Node’s child_process.exec(). Shell syntax—including pipes, redirection, substitutions, and separators—is interpreted by that shell.

const child = cmd.run(
    'git status --short',
    { cwd: './project', timeout: 30_000 },
    (error, stdout, stderr) => {
        if (error) {
            console.error(stderr || error.message);
            return;
        }
        console.log(stdout);
    }
);

console.log(child.pid);

Callback

(error, data, stderr). data is stdout, preserving the classic node-cmd callback name.

Without callback

The command still starts. Consume child.stdout, child.stderr, and lifecycle events directly.

Return

Always the immediate ChildProcess returned by Node.

runPromise(command, options?)

Runs the same shell-string path and resolves after buffered execution completes.

const task = cmd.runPromise('npm test', {
    cwd: './project',
    timeout: 30_000
});

console.log(task.child.pid);
const { stdout, stderr } = await task;

The Promise exposes Node’s immediate process handle as task.child. On nonzero exit, timeout, buffer overflow, or cancellation, it rejects with Node’s execution error; collected stdout and stderr remain attached to that error.

runSync(command, options?)

Uses execSync() and preserves node-cmd’s non-throwing result envelope for ordinary execution and validation failures.

const result = cmd.runSync('node --version');

if (result.err) {
    console.error(result.stderr || result.err);
} else {
    console.log(result.data);
}

Defaults are encoding: 'utf8' and stdio: 'pipe'. Explicit non-undefined option values win. Use encoding: 'buffer' or null for buffers.

runFile*

The direct methods call Node’s execFile family. The executable and arguments stay separate, and no shell starts unless options.shell is explicitly enabled.

const values = ['with spaces', 'semi;colon', 'ampersand&value'];

const { stdout } = await cmd.runFilePromise(
    'tool',
    ['--format', 'json', '--value', ...values],
    { cwd: './project' }
);

runFile

Callback form; returns the immediate ChildProcess.

runFilePromise

Resolves {stdout, stderr}; the returned Promise exposes .child.

runFileSync

Returns the same {data, err, stderr} envelope as runSync.

args may be omitted, undefined, or null. An options object may occupy that position. Callback overloads accept (file, callback), (file, args, callback), (file, options, callback), and (file, args, options, callback).

runStream(file, args?, options?)

Wraps child_process.spawn() for long-running, interactive, or high-output programs. Output is not accumulated into a final object, so maxBuffer and buffered-output encoding do not apply.

const child = cmd.runStream(
    'node',
    ['worker.js'],
    { stdio: ['pipe', 'pipe', 'pipe'] }
);

child.stdout.setEncoding('utf8');
child.stdout.on('data', console.log);
child.stdin.write('start\n');
child.once('close', (code, signal) => {
    console.log({ code, signal });
});

Set stream encodings on the streams themselves. The no-shell default keeps each element of args as one argument. Enabling options.shell restores shell parsing and its security implications.