namespace

$

function $(

strings: TemplateStringsArray,

The Bun shell is a powerful tool for running shell commands.

const result = await $`echo "Hello, world!"`.text();
console.log(result); // "Hello, world!"

namespace $

class ShellError
ShellError represents an error that occurred while executing a shell command with the Bun Shell.
try { const result = await $`exit 1`; } catch (error) { if (error instanceof ShellError) { console.log(error.exitCode); // 1 } }
- cause?: unknown
  The cause of the error.
- readonly exitCode: number
- message: string
- name: string
- stack?: string
- readonly stderr: Buffer
- readonly stdout: Buffer
- static stackTraceLimit: number
  The maximum number of stack frames to capture.
- arrayBuffer(): ArrayBuffer;
  Read from stdout as an ArrayBuffer
  @returns
  Stdout as an ArrayBuffer
  const output = await $`echo hello`; console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }
- blob(): Blob;
  Read from stdout as a Blob
  @returns
  Stdout as a blob
  const output = await $`echo hello`; console.log(output.blob()); // Blob { size: 6, type: "" }
- bytes(): Uint8Array;
  Read from stdout as an Uint8Array
  @returns
  Stdout as an Uint8Array
  const output = await $`echo hello`; console.log(output.bytes()); // Uint8Array { byteLength: 6 }
- json(): any;
  Read from stdout as a JSON object
  @returns
  Stdout as a JSON object
  const output = await $`echo '{"hello": 123}'`; console.log(output.json()); // { hello: 123 }
- text(
  encoding?: BufferEncoding
  ): string;
  Read from stdout as a string
  @param encoding
  The encoding to use when decoding the output
  @returns
  Stdout as a string with the given encoding
  Read as UTF-8 string
  const output = await $`echo hello`; console.log(output.text()); // "hello\n"
  Read as base64 string
  const output = await $`echo ${atob("hello")}`; console.log(output.text("base64")); // "hello\n"
- static captureStackTrace(
  targetObject: object,
  constructorOpt?: Function
  ): void;
  Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.
  const myObject = {}; Error.captureStackTrace(myObject); myObject.stack; // Similar to `new Error().stack`
  The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.
  The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.
  The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:
  function a() { b(); } function b() { c(); } function c() { // Create an error without stack trace to avoid calculating the stack trace twice. const { stackTraceLimit } = Error; Error.stackTraceLimit = 0; const error = new Error(); Error.stackTraceLimit = stackTraceLimit; // Capture the stack trace above function b Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace throw error; } a();
- static isError(
  value: unknown
  ): value is Error;
  Check if a value is an instance of Error
  @param value
  The value to check
  @returns
  True if the value is an instance of Error, false otherwise
- static prepareStackTrace(
  err: Error,
  stackTraces: CallSite[]
  ): any;
class ShellPromise
The Bun.$.ShellPromise class represents a shell command that gets executed once awaited, or called with .text(), .json(), etc.
const myShellPromise = $`echo "Hello, world!"`; const result = await myShellPromise.text(); console.log(result); // "Hello, world!"
- readonly [Symbol.toStringTag]: string
- readonly static [Symbol.species]: PromiseConstructor
- arrayBuffer(): Promise<ArrayBuffer>;
  Read from stdout as an ArrayBuffer
  Automatically calls quiet
  @returns
  A promise that resolves with stdout as an ArrayBuffer
  const output = await $`echo hello`.arrayBuffer(); console.log(output); // ArrayBuffer { byteLength: 6 }
- blob(): Promise<Blob>;
  Read from stdout as a Blob
  Automatically calls quiet
  @returns
  A promise that resolves with stdout as a Blob
  const output = await $`echo hello`.blob(); console.log(output); // Blob { size: 6, type: "" }
- catch<TResult = never>(
  onrejected?: null | (reason: any) => TResult | PromiseLike<TResult>
  ): Promise<ShellOutput | TResult>;
  Attaches a callback for only the rejection of the Promise.
  @param onrejected
  The callback to execute when the Promise is rejected.
  @returns
  A Promise for the completion of the callback.
- cwd(
  newCwd: string
  ): this;
  Change the current working directory of the shell.
  @param newCwd
  The new working directory
- env(
  newEnv: undefined | Record<string, string>
  ): this;
  Set environment variables for the shell.
  @param newEnv
  The new environment variables
  await $`echo $FOO`.env({ ...process.env, FOO: "LOL!" }) expect(stdout.toString()).toBe("LOL!");
- finally(
  onfinally?: null | () => void
  ): Promise<ShellOutput>;
  Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.
  @param onfinally
  The callback to execute when the Promise is settled (fulfilled or rejected).
  @returns
  A Promise for the completion of the callback.
- json(): Promise<any>;
  Read from stdout as a JSON object
  Automatically calls quiet
  @returns
  A promise that resolves with stdout as a JSON object
  const output = await $`echo '{"hello": 123}'`.json(); console.log(output); // { hello: 123 }
- lines(): AsyncIterable<string>;
  Read from stdout as a string, line by line
  Automatically calls quiet to disable echoing to stdout.
- nothrow(): this;
  Configure the shell to not throw an exception on non-zero exit codes. Throwing can be re-enabled with .throws(true).
  By default, the shell with throw an exception on commands which return non-zero exit codes.
- quiet(): this;
  By default, the shell will write to the current process's stdout and stderr, as well as buffering that output.
  This configures the shell to only buffer the output.
- text(
  encoding?: BufferEncoding
  ): Promise<string>;
  Read from stdout as a string.
  Automatically calls quiet to disable echoing to stdout.
  @param encoding
  The encoding to use when decoding the output
  @returns
  A promise that resolves with stdout as a string
  Read as UTF-8 string
  const output = await $`echo hello`.text(); console.log(output); // "hello\n"
  Read as base64 string
  const output = await $`echo ${atob("hello")}`.text("base64"); console.log(output); // "hello\n"
- then<TResult1 = ShellOutput, TResult2 = never>(
  onfulfilled?: null | (value: ShellOutput) => TResult1 | PromiseLike<TResult1>,
  onrejected?: null | (reason: any) => TResult2 | PromiseLike<TResult2>
  ): Promise<TResult1 | TResult2>;
  Attaches callbacks for the resolution and/or rejection of the Promise.
  @param onfulfilled
  The callback to execute when the Promise is resolved.
  @param onrejected
  The callback to execute when the Promise is rejected.
  @returns
  A Promise for the completion of which ever callback is executed.
- throws(
  shouldThrow: boolean
  ): this;
  Configure whether or not the shell should throw an exception on non-zero exit codes.
  By default, this is configured to true.
- static all<T extends [] | readonly unknown[]>(
  values: T
  ): Promise<{ [K in string | number | symbol]: Awaited<T[P<P>]> }>;
  Creates a Promise that is resolved with an array of results when all of the provided Promises resolve, or rejected when any Promise is rejected.
  @param values
  An array of Promises.
  @returns
  A new Promise.
- static allSettled<T>(
  values: Iterable<T | PromiseLike<T>>
  ): Promise<PromiseSettledResult<Awaited<T>>[]>;
  Creates a Promise that is resolved with an array of results when all of the provided Promises resolve or reject.
  @param values
  An array of Promises.
  @returns
  A new Promise.
- static any<T extends [] | readonly unknown[]>(
  values: T
  ): Promise<Awaited<T[number]>>;
  The any function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an AggregateError containing an array of rejection reasons if all of the given promises are rejected. It resolves all elements of the passed iterable to promises as it runs this algorithm.
  @param values
  An array or iterable of Promises.
  @returns
  A new Promise.
- static race<T extends [] | readonly unknown[]>(
  values: T
  ): Promise<Awaited<T[number]>>;
  Creates a Promise that is resolved or rejected when any of the provided Promises are resolved or rejected.
  @param values
  An array of Promises.
  @returns
  A new Promise.
- static reject<T = never>(
  reason?: any
  ): Promise<T>;
  Creates a new rejected promise for the provided reason.
  @param reason
  The reason the promise was rejected.
  @returns
  A new rejected Promise.
- static resolve<T>(
  value: T
  ): Promise<Awaited<T>>;
  Creates a new resolved promise for the provided value.
  @param value
  A promise.
  @returns
  A promise whose internal state matches the provided promise.
- static try<T, A extends any[] = []>(
  fn: (...args: A) => T | PromiseLike<T>,
  ...args: A
  ): Promise<T>;
  Try to run a function and return the result. If the function throws, return the result of the catch function.
  @param fn
  The function to run
  @param args
  The arguments to pass to the function. This is similar to setTimeout and avoids the extra closure.
  @returns
  The result of the function or the result of the catch function
- static withResolvers<T>(): { promise: Promise<T>; reject: (reason?: any) => void; resolve: (value?: T | PromiseLike<T>) => void };
  Create a deferred promise, with exposed resolve and reject methods which can be called separately.
  This is useful when you want to return a Promise and have code outside the Promise resolve or reject it.
  const { promise, resolve, reject } = Promise.withResolvers(); setTimeout(() => { resolve("Hello world!"); }, 1000); await promise; // "Hello world!"
interface ShellOutput
- readonly exitCode: number
- readonly stderr: Buffer
- readonly stdout: Buffer
- arrayBuffer(): ArrayBuffer;
  Read from stdout as an ArrayBuffer
  @returns
  Stdout as an ArrayBuffer
  const output = await $`echo hello`; console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }
- blob(): Blob;
  Read from stdout as a Blob
  @returns
  Stdout as a blob
  const output = await $`echo hello`; console.log(output.blob()); // Blob { size: 6, type: "" }
- bytes(): Uint8Array;
  Read from stdout as an Uint8Array
  @returns
  Stdout as an Uint8Array
  const output = await $`echo hello`; console.log(output.bytes()); // Uint8Array { byteLength: 6 }
- json(): any;
  Read from stdout as a JSON object
  @returns
  Stdout as a JSON object
  const output = await $`echo '{"hello": 123}'`; console.log(output.json()); // { hello: 123 }
- text(
  encoding?: BufferEncoding
  ): string;
  Read from stdout as a string
  @param encoding
  The encoding to use when decoding the output
  @returns
  Stdout as a string with the given encoding
  Read as UTF-8 string
  const output = await $`echo hello`; console.log(output.text()); // "hello\n"
  Read as base64 string
  const output = await $`echo ${atob("hello")}`; console.log(output.text("base64")); // "hello\n"
const Shell: new () => $
function braces(
pattern: string
): string[];
Perform bash-like brace expansion on the given pattern.
@param pattern
Brace pattern to expand
const result = braces('index.{js,jsx,ts,tsx}'); console.log(result) // ['index.js', 'index.jsx', 'index.ts', 'index.tsx']
function cwd(
newCwd?: string
): typeof $;
@param newCwd
Default working directory to use for shells created by this instance.
function env(
newEnv?: Record<string, undefined | string>
): typeof $;
Change the default environment variables for shells created by this instance.
@param newEnv
Default environment variables to use for shells created by this instance.
import {$} from 'bun'; $.env({ BUN: "bun" }); await $`echo $BUN`; // "bun"
function escape(
input: string
): string;
Escape strings for input into shell commands.
function nothrow(): typeof $;
Configure the shell to not throw an exception on non-zero exit codes.
function throws(
shouldThrow: boolean
): typeof $;
Configure whether or not the shell should throw an exception on non-zero exit codes.

$

namespace $

class ShellError

class ShellPromise

interface ShellOutput