Home

dollar-shell

About

The dollar-shell is a micro-library for running shell commands and using them in streams with ease in Node, Deno, Bun. It is a tiny, simple, no dependency package with TypeScript typings.

All streams are created using web streams. See Cross-runtime notes for the small ways Node, Bun, and Deno differ in practice.

The dollar-shell package can be used together with stream-chain and stream-json to create efficient pipelines.

Installation

npm i --save dollar-shell

Usage

import {$, $sh} from 'dollar-shell';

Search

🔍 Search this wiki — ranked, deep-linked search via wiki-search; install the bookmarklet to search in place. Fallback: GitHub wiki search.

Documentation

The package exports the following names:

• $ — spawns a process using a template string. It includes the following helpers, which all spawn a process using a template string:
  • $.from — returns its stdout as a source stream.
  • $.to — returns its stdin as a sink stream.
  • $.io AKA $.through — returns a readable/writeable pair, which can be used as a transformation step in a pipeline.
• $sh — spawns a shell process using a template string. It includes the following helpers, which all spawn a shell process using a template string:
  • $sh.from — returns its stdout as a source stream.
  • $sh.to — returns its stdin as a sink stream.
  • $sh.io AKA $sh.through — returns a readable/writeable pair, which can be used as a transformation step in a pipeline.
• spawn() — spawns a process with advanced ways to configure and control it.
• $$ — spawns a process using a template string based on spawn().
• shell AKA sh — a helper to spawn a shell command using a template string.
• capture — spawns a process using a template string and collects its stdout/stderr as strings along with the exit status — the one-call scripting and testing primitive.
• Various internal utilities:
  • Template string helpers:
    • raw()
    • winCmdEscape()
  • Platform detection:
    • isWindows
  • spawn() and shell helpers:
    • cwd()
    • currentExecPath()
    • runFileArgs
    • shellEscape()
    • currentShellPath()
  • Shell command builders:
    • buildShellCommand()

$ is used as the default export.

For Node streams instead of web streams, import from dollar-shell/node — the same API with Node Readable/Writable on stdin/stdout/stderr.

See Release notes for the version history.

For AI Agents

This package includes files to help AI coding agents and LLMs find, understand, and use it:

• AGENTS.md: Project conventions, architecture, commands, and coding guidelines
• CLAUDE.md: Claude Code instructions (redirects to AGENTS.md)
• CONTRIBUTING.md: Contribution guidelines for humans and AI agents
• llms.txt: Concise overview following the llms.txt standard
• llms-full.txt: Self-contained complete API reference

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.