Shell - Bun

Bun Shell makes shell scripting with JavaScript & TypeScript fun. It’s a cross-platform bash-like shell with seamless JavaScript interop. Quickstart:

https://mintcdn.com/bun-1dd33a4e-farm-a91c5779-shell-sandbox/CFA6Tagw86uhJFhY/icons/typescript.svg?fit=max&auto=format&n=CFA6Tagw86uhJFhY&q=85&s=b76cf0e4a2c188862bc272cae1c4e52f

index.ts

import { $ } from "bun";

const response = await fetch("https://example.com");

// Use Response as stdin.
await $`cat < ${response} | wc -c`; // 1256

Features

Cross-platform: works on Windows, Linux & macOS. Instead of rimraf or cross-env’, you can use Bun Shell without installing extra dependencies. Common shell commands like ls, cd, rm are implemented natively.
Familiar: Bun Shell is a bash-like shell, supporting redirection, pipes, environment variables and more.
Globs: Glob patterns are supported natively, including **, *, {expansion}, and more.
Template literals: Template literals execute shell commands, allowing interpolation of variables and expressions.
Safety: Bun Shell escapes all strings by default, preventing shell injection attacks.
JavaScript interop: Use Response, ArrayBuffer, Blob, Bun.file(path) and other JavaScript objects as stdin, stdout, and stderr.
Shell scripting: Bun Shell can be used to run shell scripts (.bun.sh files).
Custom interpreter: Bun Shell is written in Zig, along with its lexer, parser, and interpreter. Bun Shell is a small programming language.

Getting started

The simplest shell command is echo. To run it, use the $ template literal tag:

import { $ } from "bun";

await $`echo "Hello World!"`; // Hello World!

By default, shell commands print to stdout. To quiet the output, call .quiet():

import { $ } from "bun";

await $`echo "Hello World!"`.quiet(); // No output

What if you want to access the output of the command as text? Use .text():

import { $ } from "bun";

// .text() automatically calls .quiet() for you
const welcome = await $`echo "Hello World!"`.text();

console.log(welcome); // Hello World!\n

By default, awaiting will return stdout and stderr as Buffers.

import { $ } from "bun";

const { stdout, stderr } = await $`echo "Hello!"`.quiet();

console.log(stdout); // Buffer(7) [ 72, 101, 108, 108, 111, 33, 10 ]
console.log(stderr); // Buffer(0) []

Error handling

By default, non-zero exit codes will throw an error. This ShellError contains information about the command run.

import { $ } from "bun";

try {
  const output = await $`something-that-may-fail`.text();
  console.log(output);
} catch (err) {
  console.log(`Failed with code ${err.exitCode}`);
  console.log(err.stdout.toString());
  console.log(err.stderr.toString());
}

Throwing can be disabled with .nothrow(). The result’s exitCode will need to be checked manually.

import { $ } from "bun";

const { stdout, stderr, exitCode } = await $`something-that-may-fail`.nothrow().quiet();

if (exitCode !== 0) {
  console.log(`Non-zero exit code ${exitCode}`);
}

console.log(stdout);
console.log(stderr);

The default handling of non-zero exit codes can be configured by calling .nothrow() or .throws(boolean) on the $ function itself.

import { $ } from "bun";
// shell promises will not throw, meaning you will have to
// check for `exitCode` manually on every shell command.
$.nothrow(); // equivalent to $.throws(false)

// default behavior, non-zero exit codes will throw an error
$.throws(true);

// alias for $.nothrow()
$.throws(false);

await $`something-that-may-fail`; // No exception thrown

Redirection

A command’s input or output may be redirected using the typical Bash operators:

< redirect stdin
> or 1> redirect stdout
2> redirect stderr
&> redirect both stdout and stderr
>> or 1>> redirect stdout, appending to the destination, instead of overwriting
2>> redirect stderr, appending to the destination, instead of overwriting
&>> redirect both stdout and stderr, appending to the destination, instead of overwriting
1>&2 redirect stdout to stderr (all writes to stdout will instead be in stderr)
2>&1 redirect stderr to stdout (all writes to stderr will instead be in stdout)

Bun Shell also supports redirecting from and to JavaScript objects.

Example: Redirect output to JavaScript objects (`>`)

To redirect stdout to a JavaScript object, use the > operator:

import { $ } from "bun";

const buffer = Buffer.alloc(100);
await $`echo "Hello World!" > ${buffer}`;

console.log(buffer.toString()); // Hello World!\n

The following JavaScript objects are supported for redirection to:

Buffer, Uint8Array, Uint16Array, Uint32Array, Int8Array, Int16Array, Int32Array, Float32Array, Float64Array, ArrayBuffer, SharedArrayBuffer (writes to the underlying buffer)
Bun.file(path), Bun.file(fd) (writes to the file)

Example: Redirect input from JavaScript objects (`<`)

To redirect the output from JavaScript objects to stdin, use the < operator:

import { $ } from "bun";

const response = new Response("hello i am a response body");

const result = await $`cat < ${response}`.text();

console.log(result); // hello i am a response body

The following JavaScript objects are supported for redirection from:

Buffer, Uint8Array, Uint16Array, Uint32Array, Int8Array, Int16Array, Int32Array, Float32Array, Float64Array, ArrayBuffer, SharedArrayBuffer (reads from the underlying buffer)
Bun.file(path), Bun.file(fd) (reads from the file)
Response (reads from the body)

Example: Redirect stdin -> file

import { $ } from "bun";

await $`cat < myfile.txt`;

Example: Redirect stdout -> file

import { $ } from "bun";

await $`echo bun! > greeting.txt`;

Example: Redirect stderr -> file

import { $ } from "bun";

await $`bun run index.ts 2> errors.txt`;

Example: Redirect stderr -> stdout

import { $ } from "bun";

// redirects stderr to stdout, so all output
// will be available on stdout
await $`bun run ./index.ts 2>&1`;

Example: Redirect stdout -> stderr

import { $ } from "bun";

// redirects stdout to stderr, so all output
// will be available on stderr
await $`bun run ./index.ts 1>&2`;

Piping (`|`)

Like in bash, you can pipe the output of one command to another:

import { $ } from "bun";

const result = await $`echo "Hello World!" | wc -w`.text();

console.log(result); // 2\n

You can also pipe with JavaScript objects:

import { $ } from "bun";

const response = new Response("hello i am a response body");

const result = await $`cat < ${response} | wc -w`.text();

console.log(result); // 6\n

Command substitution (`$(...)`)

Command substitution allows you to substitute the output of another script into the current script:

import { $ } from "bun";

// Prints out the hash of the current commit
await $`echo Hash of current commit: $(git rev-parse HEAD)`;

This is a textual insertion of the command’s output and can be used to, for example, declare a shell variable:

import { $ } from "bun";

await $`
  REV=$(git rev-parse HEAD)
  docker built -t myapp:$REV
  echo Done building docker image "myapp:$REV"
`;

Because Bun internally uses the special raw property on the input template literal, using the backtick syntax for command substitution won’t work:

import { $ } from "bun";

await $`echo \`echo hi\``;

Instead of printing:

hi

The above will print out:

echo hi

We instead recommend sticking to the $(...) syntax.

Environment variables

Environment variables can be set like in bash:

import { $ } from "bun";

await $`FOO=foo bun -e 'console.log(process.env.FOO)'`; // foo\n

You can use string interpolation to set environment variables:

import { $ } from "bun";

const foo = "bar123";

await $`FOO=${foo + "456"} bun -e 'console.log(process.env.FOO)'`; // bar123456\n

Input is escaped by default, preventing shell injection attacks:

import { $ } from "bun";

const foo = "bar123; rm -rf /tmp";

await $`FOO=${foo} bun -e 'console.log(process.env.FOO)'`; // bar123; rm -rf /tmp\n

Changing the environment variables

By default, process.env is used as the environment variables for all commands. You can change the environment variables for a single command by calling .env():

import { $ } from "bun";

await $`echo $FOO`.env({ ...process.env, FOO: "bar" }); // bar

You can change the default environment variables for all commands by calling $.env:

import { $ } from "bun";

$.env({ FOO: "bar" });

// the globally-set $FOO
await $`echo $FOO`; // bar

// the locally-set $FOO
await $`echo $FOO`.env({ FOO: "baz" }); // baz

You can reset the environment variables to the default by calling $.env() with no arguments:

import { $ } from "bun";

$.env({ FOO: "bar" });

// the globally-set $FOO
await $`echo $FOO`; // bar

// the locally-set $FOO
await $`echo $FOO`.env(undefined); // ""

Changing the working directory

You can change the working directory of a command by passing a string to .cwd():

import { $ } from "bun";

await $`pwd`.cwd("/tmp"); // /tmp

You can change the default working directory for all commands by calling $.cwd:

import { $ } from "bun";

$.cwd("/tmp");

// the globally-set working directory
await $`pwd`; // /tmp

// the locally-set working directory
await $`pwd`.cwd("/"); // /

Reading output

To read the output of a command as a string, use .text():

import { $ } from "bun";

const result = await $`echo "Hello World!"`.text();

console.log(result); // Hello World!\n

Reading output as JSON

To read the output of a command as JSON, use .json():

import { $ } from "bun";

const result = await $`echo '{"foo": "bar"}'`.json();

console.log(result); // { foo: "bar" }

Reading output line-by-line

To read the output of a command line-by-line, use .lines():

import { $ } from "bun";

for await (let line of $`echo "Hello World!"`.lines()) {
  console.log(line); // Hello World!
}

You can also use .lines() on a completed command:

import { $ } from "bun";

const search = "bun";

for await (let line of $`cat list.txt | grep ${search}`.lines()) {
  console.log(line);
}

Reading output as a Blob

To read the output of a command as a Blob, use .blob():

import { $ } from "bun";

const result = await $`echo "Hello World!"`.blob();

console.log(result); // Blob(13) { size: 13, type: "text/plain" }

Builtin Commands

For cross-platform compatibility, Bun Shell implements a set of builtin commands, in addition to reading commands from the PATH environment variable.

cd: change the working directory
ls: list files in a directory (supports -l for long listing format)
rm: remove files and directories
echo: print text
pwd: print the working directory
bun: run bun in bun
cat
touch
mkdir
which
mv
exit
true
false
yes
seq
dirname
basename

Partially implemented:

mv: move files and directories (missing cross-device support)

Not implemented yet, but planned:

See Issue #9716 for the full list.

Utilities

Bun Shell also implements a set of utilities for working with shells.

`$.braces` (brace expansion)

This function implements simple brace expansion for shell commands:

import { $ } from "bun";

await $.braces(`echo {1,2,3}`);
// => ["echo 1", "echo 2", "echo 3"]

`$.escape` (escape strings)

Exposes Bun Shell’s escaping logic as a function:

import { $ } from "bun";

console.log($.escape('$(foo) `bar` "baz"'));
// => \$(foo) \`bar\` \"baz\"

If you do not want your string to be escaped, wrap it in a { raw: 'str' } object:

import { $ } from "bun";

await $`echo ${{ raw: '$(foo) `bar` "baz"' }}`;
// => bun: command not found: foo
// => bun: command not found: bar
// => baz

`.sh` file loader

For simple shell scripts, instead of /bin/sh, you can use Bun Shell to run shell scripts. To do so, run the script with bun on a file with the .sh extension.

script.sh

echo "Hello World! pwd=$(pwd)"

terminal

bun ./script.sh

Hello World! pwd=/home/demo

Scripts with Bun Shell are cross platform, which means they work on Windows:

powershell

bun .\script.sh

Hello World! pwd=C:\Users\Demo

Implementation notes

Bun Shell is a small programming language in Bun that is implemented in Zig. It includes a handwritten lexer, parser, and interpreter. Unlike bash, zsh, and other shells, Bun Shell runs operations concurrently.

Security in the Bun shell

By design, the Bun shell does not invoke a system shell (like /bin/sh) and is instead a re-implementation of bash that runs in the same Bun process, designed with security in mind. When parsing command arguments, it treats all interpolated variables as single, literal strings. This protects the Bun shell against command injection:

import { $ } from "bun";

const userInput = "my-file.txt; rm -rf /";

// SAFE: `userInput` is treated as a single quoted string
await $`ls ${userInput}`;

In the above example, userInput is treated as a single string. This causes the ls command to try to read the contents of a single directory named “my-file; rm -rf /”.

Security considerations

While command injection is prevented by default, developers are still responsible for security in certain scenarios. Similar to the Bun.spawn or node:child_process.exec() APIs, you can intentionally execute a command which spawns a new shell (e.g. bash -c) with arguments. When you do this, you hand off control, and Bun’s built-in protections no longer apply to the string interpreted by that new shell.

import { $ } from "bun";

const userInput = "world; touch /tmp/pwned";

// UNSAFE: You have explicitly started a new shell process with `bash -c`.
// This new shell will execute the `touch` command. Any user input
// passed this way must be rigorously sanitized.
await $`bash -c "echo ${userInput}"`;

Argument injection

The Bun shell cannot know how an external command interprets its own command-line arguments. An attacker can supply input that the target program recognizes as one of its own options or flags, leading to unintended behavior.

import { $ } from "bun";

// Malicious input formatted as a Git command-line flag
const branch = "--upload-pack=echo pwned";

// UNSAFE: While Bun safely passes the string as a single argument,
// the `git` program itself sees and acts upon the malicious flag.
await $`git ls-remote origin ${branch}`;

Recommendation — As is best practice in every language, always sanitize user-provided input before passing it as an argument to an external command. The responsibility for validating arguments rests with your application code.

Sandboxed shells (experimental)

$.sandbox(options) creates a restricted shell for running untrusted shell commands. Because Bun Shell implements its commands natively, the policy is enforced inside the interpreter, before any command or filesystem operation executes.

import { $ } from "bun";

const box = $.sandbox({
  commands: { deny: ["rm"] },
  fs: {
    read: ["/workspace/data"],
    write: ["/workspace/data/out"],
  },
  limits: { timeout: 5_000, maxOutputBytes: 1024 * 1024 },
});

await box`ls /workspace/data`; // ok
await box`cat /etc/passwd`; // fails: read access not permitted in sandbox
await box`git status`; // fails: external commands are not permitted in sandbox

The returned function is $-compatible: it supports interpolation, .cwd(), .env(), .quiet(), .nothrow(), .text(), and friends, and inherits the cwd/env/throws configuration of the shell it derives from (Bun.$ or a new $.Shell() instance). A sandboxed shell cannot be re-sandboxed; derive a new sandbox from an unsandboxed shell instead. Blocked commands and file operations fail with exit code 1 and a ... not permitted in sandbox message on stderr, so they compose with &&, ||, and .nothrow() like any other failing command. Exceeded limits reject the promise with a descriptive error.

Command policy

Only Bun Shell builtins can run inside a sandbox — external binaries are always blocked, before any PATH lookup happens. commands.allow and commands.deny restrict the builtin set further:

const box = $.sandbox({
  commands: {
    allow: ["echo", "ls", "seq"], // only these builtins may run
    deny: ["rm"], // deny always wins over allow
  },
});

Unknown command names in allow/deny throw, listing the valid builtin names. The available builtin set matches the regular shell’s: on POSIX platforms cat and cp currently delegate to system binaries, so inside a sandbox they are blocked like any external command. Because external binaries cannot run, environment tricks like PATH=/evil cmd cannot smuggle a command in, and which never probes the host filesystem — it only reports policy-permitted builtins.

Filesystem policy

By default a sandboxed shell has no filesystem access. fs.read and fs.write grant access under absolute path prefixes; a write prefix also grants read. Omit write for a read-only sandbox. Every path the script touches — command operands, redirect targets, glob walks, cd, and [[ -f ... ]] tests — is resolved against the shell’s working directory and through symlinks before it is compared against the prefixes. This is what stops the classic escapes:

const box = $.sandbox({ fs: { read: ["/workspace/data"] } });

await box`ls /workspace/data/../secrets`; // fails: `..` is resolved first
await box`echo x < /workspace/data/link`; // fails if `link` points outside
await box`echo /etc/*`; // fails: glob walks outside the prefixes are refused
await box`cd /etc`; // fails: the new cwd must be readable

File tests like [[ -f /etc/passwd ]] answer as if the file does not exist, so scripts cannot probe the host tree. Recursive operations (ls -R, rm -r) stay under their checked roots because traversal never follows symlinks. Paths granted to the policy and paths checked at runtime are both canonicalized the same way (symlinks resolved via the deepest existing ancestor), so grants work even when the directory itself is reached through a symlink, such as /tmp on macOS.

Network policy

A sandboxed script cannot reach the network: external binaries are blocked, and no shell builtin performs network I/O. The network option is reserved for future allowlists and currently only accepts false (the default); passing true throws.

Limits

limits.timeout — wall-clock limit in milliseconds for the whole script. When it expires, the promise rejects with Shell command timed out after <n>ms (sandbox limits.timeout) and the interpreter stops scheduling work.
limits.maxOutputBytes — caps the total bytes the script may write to stdout, stderr, and file redirects combined. When exceeded, the promise rejects with Shell command output exceeded <n> bytes (sandbox limits.maxOutputBytes).

Both rejections carry the output captured up to that point on error.stdout / error.stderr.

Current limitations

This API is experimental, and the policy surface is designed to grow (finer-grained network rules and an overlay filesystem where writes land in a scratch layer are planned). Current limitations to be aware of:

JavaScript objects interpolated into the command (Bun.file(), Response, buffers) are provided by the calling code, not the untrusted script, so they are intentionally not subject to the filesystem policy.
A builtin blocked forever on a pipe that never receives data keeps its read poll active after a timeout; the promise still rejects and the caller regains control.
Path checks happen when an operation starts. With external binaries disabled, scripts cannot race the interpreter from another thread, but processes outside the sandbox mutating the same tree concurrently can still change what a checked path points at.

Credits

Large parts of this API were inspired by zx, dax, and bnx. Thank you to the authors of those projects.

​Features

​Getting started

​Error handling

​Redirection

​Example: Redirect output to JavaScript objects (>)

​Example: Redirect input from JavaScript objects (<)

​Example: Redirect stdin -> file

​Example: Redirect stdout -> file

​Example: Redirect stderr -> file

​Example: Redirect stderr -> stdout

​Example: Redirect stdout -> stderr

​Piping (|)

​Command substitution ($(...))

​Environment variables

​Changing the environment variables

​Changing the working directory

​Reading output

​Reading output as JSON

​Reading output line-by-line

​Reading output as a Blob

​Builtin Commands

​Utilities

​$.braces (brace expansion)

​$.escape (escape strings)

​.sh file loader

​Implementation notes

​Security in the Bun shell

​Security considerations

​Argument injection

​Sandboxed shells (experimental)

​Command policy

​Filesystem policy

​Network policy

​Limits

​Current limitations

​Credits

Features

Getting started

Error handling

Redirection

Example: Redirect output to JavaScript objects (`>`)

Example: Redirect input from JavaScript objects (`<`)

Example: Redirect stdin -> file

Example: Redirect stdout -> file

Example: Redirect stderr -> file

Example: Redirect stderr -> stdout

Example: Redirect stdout -> stderr

Piping (`|`)

Command substitution (`$(...)`)

Environment variables

Changing the environment variables

Changing the working directory

Reading output

Reading output as JSON

Reading output line-by-line

Reading output as a Blob

Builtin Commands

Utilities

`$.braces` (brace expansion)

`$.escape` (escape strings)

`.sh` file loader

Implementation notes

Security in the Bun shell

Security considerations

Argument injection

Sandboxed shells (experimental)

Command policy

Filesystem policy

Network policy

Limits

Current limitations

Credits