package
Run OS and shell commands using template tag functions. Same API in Node, Deno, and Bun. Web streams, TypeScript typings, zero dependencies.
npm install dollar-shellGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
70.6 kB
Includes dependencies.
dollar-shell is a micro-library for running OS and shell commands from JavaScript/TypeScript using template tag functions. It works in Node, Deno, Bun with the same API. Web streams, TypeScript typings, zero dependencies.
The idea is to run OS/shell commands and/or use them in stream pipelines as sources, sinks, and transformation steps using web streams. It can be used together with stream-chain and stream-json to create efficient pipelines. It helps using shell commands in utilities written in JavaScript/TypeScript running with Node, Deno, or Bun.
Available components:
$ — spawn a process using a template string.
$.from — spawn a process and use its stdout as a source stream.$.to — spawn a process and use its stdin as a sink stream.$.io AKA $.through — spawn a process and use it as
a transformation step in our pipeline.$sh — run a shell command using a template string.
$sh.from — run a shell command and use its stdout as a source stream.$sh.to — run a shell command and use its stdin as a sink stream.$sh.io AKA $sh.through — run a shell command and use it as
a transformation step in our pipeline.capture — run a command and collect its / as strings.Run a command:
import $ from 'dollar-shell';
const result = await $`echo hello`;
console.log(result.code, result.signal, result.killed);Run a shell command:
import {$sh} from 'dollar-shell';
const result = await $sh`ls .`;
console.log(result.code, result.signal, result.killed);Run a shell command (an alias or a function) and show its result:
import {$sh} from 'dollar-shell';
// custom alias that prints `stdout` and runs an interactive shell
const $p = $sh({shellArgs: ['-ic'], stdout: 'inherit'});
const result = await $p`nvm ls`;
// prints to the console the result of the commandRun a pipeline:
import $ from 'dollar-shell';
import chain from 'stream-chain';
import lines from 'stream-chain/utils/lines.js';
chain([
$.from`ls -l .`,
$.io`grep LICENSE`,
$.io`wc`,
new TextDecoderStream(),
lines(),
line => console.log(line)
]);Capture the output of a command:
import {capture} from 'dollar-shell';
const {code, stdout, stderr} = await capture`git rev-parse HEAD`;
// feed a string to stdin
const result = await capture({input: 'some text'})`cat`;
result.stdout === 'some text';npm i --save dollar-shellFull documentation is in the wiki — browse the index, or search it by name. See how it can be used in tests/.
For AI assistants: see llms.txt and llms-full.txt for LLM-optimized documentation.
Each runtime uses its own backend by default (node:child_process on Node, Bun.spawn on Bun,
Deno.Command on Deno). Set the DSH_FORCE_NODE environment variable (e.g. DSH_FORCE_NODE=1) to
make every runtime spawn through the Node backend — it swaps only the spawn mechanism, the
runtime launch stays native. Handy for sidestepping runtime-specific quirks. Details and scoping (the
whole process tree vs the current process only) are in the
Cross-runtime notes.
dollar-shell/node)The default entry exposes web streams on
stdin/stdout/stderr. If you'd rather work with Node streams — to pipe straight into
fs/zlib/etc. with no adapter — import the identical API from dollar-shell/node instead:
import {spawn} from 'dollar-shell/node';
const sp = spawn(['cat', 'file.txt'], {stdout: 'pipe'});
sp.stdout.pipe(process.stdout); // sp.stdout is a Node ReadableOnly the stream types differ (stdin is a Node Writable, stdout/stderr are Node Readables,
asDuplex/.io/.through return a Node Duplex). See
Node streams for details.
This package ships with files to help AI coding agents and LLMs find, understand, and use it:
The machine-readable llms.txt and llms-full.txt ship inside the npm package, so AI tools can read them straight from node_modules. AGENTS.md and CLAUDE.md are authoring-side docs kept in the repository.
BSD-3-Clause
capture (run a command, collect stdout/stderr as strings) and the signal option (an AbortSignal kills the subprocess).DSH_FORCE_NODE and dollar-shell/node now switch only the spawn mechanism — spawned children stay native (bun run … / deno run …).dollar-shell/node with Node streams and a DSH_FORCE_NODE flag to force the Node backend on any runtime.tests/, removed ts-check/, added CJS test, improved test coverage and documentation.asDuplex to the sub-process object.raw() for spawn commands.The full release notes are in the wiki: Release notes.
stdoutstderr