Run shell commands and use them in stream pipelines with ease in Node, Deno, Bun. Template tag API, web streams, TypeScript typings, zero 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.
$.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.
Introduction
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 shellconst $p = $sh({shellArgs: ['-ic'], stdout: 'inherit'});const result = await $p`nvm ls`;// prints to the console the result of the command
Run 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 stdinconst result = await capture({input: 'some text'})`cat`;result.stdout === 'some text';
Installation
npm i --save dollar-shell
Documentation
Full documentation is in the wiki — browse the index, or search it by name.
See how it can be used in tests/.
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.
Node streams (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 Readable
Only 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.
For AI Agents
This package ships with files to help AI coding agents and LLMs find, understand, and use it:
AGENTS.md — Project conventions, architecture, commands, and coding guidelines for AI agents.
CLAUDE.md — Claude Code specific instructions (redirects to AGENTS.md).
CONTRIBUTING.md — Contribution guidelines for humans and AI agents.
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.
License
BSD-3-Clause
Release History
1.3.0 Added capture (run a command, collect stdout/stderr as strings) and the signal option (an AbortSignal kills the subprocess).
1.2.1 Bugfix: DSH_FORCE_NODE and dollar-shell/node now switch only the spawn mechanism — spawned children stay native (bun run … / deno run …).
1.2.0 Added dollar-shell/node with Node streams and a DSH_FORCE_NODE flag to force the Node backend on any runtime.
1.1.14 Fixed Bun stdin abort path, added js-check, Bun + Deno wired into CI.
1.1.13 Updated dev dependencies.
1.1.12 Consolidated TypeScript tests into tests/, removed ts-check/, added CJS test, improved test coverage and documentation.
1.1.11 Updated dev dependencies.
1.1.10 Fixed a bug with options chaining for attached functions, fixed Bun spawn on invalid commands, Windows-compatible tests, updated dev dependencies.
1.1.9 Updated dev dependencies, cleaned up docs, added info for AI agents.
1.1.8 Updated dev dependencies.
1.1.7 Updated dev dependencies.
1.1.6 Updated dev dependencies.
1.1.5 Updated dev dependencies.
1.1.4 Updated dev dependencies.
1.1.3 Updated dev dependencies.
1.1.2 Updated dev dependencies.
1.1.1 Updated dev dependencies.
1.1.0 Added asDuplex to the sub-process object.
1.0.5 Updated dev dependencies.
1.0.4 Fixed raw() for spawn commands.
1.0.3 Added TSDoc comments, improved docs, fixed typos, added the missing copying of properties.
1.0.2 Technical release: fixed references in the package file.
1.0.1 Technical release: more tests, better documentation.
1.0.0
The full release notes are in the wiki: Release notes.
stdout
stderr
Advanced components:
spawn() — spawn a process with advanced ways to configure and control it.
$$ — spawn a process using a template string based on spawn().
shell() — a helper to spawn a shell command using a template string based on spawn().