01 / shell
run* speaks shell.
Use shell syntax, pipelines, redirection, and built-ins. Forward Node execution options and keep the returned ChildProcess.
v6.0.1 Process control for Node.js
Command-line power for Node.js.
Run shell commands, launch executables, stream output, write to stdin, and control child processes from Node.js—with zero runtime dependencies.
- Classic
run/runSync - Node.js CommonJS + ESM
- Node.js 22.12+
process://node-cmd
running// direct executable + real ChildProcess
const child = cmd.runStream(
'git', ['status', '--short']
);
child.stdout.pipe(process.stdout);
PID4812
STDOUTstreaming
EXIT0
JavaScript owns the process
pidstdinstdoutstderrkill()
0runtime dependencies
9public methods
53/53focused tests passing
100%statements covered
Why node-cmd?
One small API for common process shapes.
Node already provides node:child_process. node-cmd makes its common execution paths consistent while keeping the important boundary—shell string, exact arguments, or live stream—obvious at the call site.
run*for intentional shell syntax;runFile*andrunStream()for separate arguments by default.- Callback, Promise, synchronous, buffered, and streaming control without a production dependency tree.
- Classic calls stay valid, while CommonJS and ESM load the same implementation on Node.js 22.12+.
Choose the execution boundary
Shell strings, exact arguments, or live streams.
The method name tells reviewers whether a shell parses the input, whether output is buffered, and whether the caller keeps a live process handle.
02 / direct
runFile* preserves arguments.
Pass an executable and argument array without a shell by default—the safer boundary for variable input.
03 / stream
runStream stays unbuffered.
Use stdin, stdout, stderr, PID, signals, and lifecycle events for long-running or high-output programs.
04 / result
Callback, Promise, or sync.
Keep legacy callbacks, await buffered output, or use the stable synchronous result envelope.
Install and execute
JavaScript in. Operating-system process out.
In Node.js, consume either shipped entry directly—no transpiler, bundler, TypeScript runtime, or application dependency tree.
Install node-cmd
npm install node-cmdconst cmd = require('node-cmd');
const child = cmd.run(
'git status --short',
{ cwd: './project' },
(error, stdout, stderr) => {
if (error) throw error;
console.log(stdout);
}
);
console.log(child.pid);import { runPromise } from 'node-cmd';
const task = runPromise(
'npm test',
{ cwd: './project', timeout: 30_000 }
);
console.log(task.child.pid);
const { stdout, stderr } = await task;import { runFilePromise } from 'node-cmd';
const { stdout } = await runFilePromise(
'git',
['log', '-1', '--oneline'],
{ cwd: './project' }
);Engineering documentation
Reference material lives on real pages.
Open the document you need without navigating a single oversized landing page.