class ShellPromise | Bun module | Bun

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!"

Read from stdout as an ArrayBuffer

Automatically calls quiet

A promise that resolves with stdout as an ArrayBuffer

const output = await $`echo hello`.arrayBuffer();
console.log(output); // ArrayBuffer { byteLength: 6 }

Read from stdout as a Blob

Automatically calls quiet

A promise that resolves with stdout as a Blob

const output = await $`echo hello`.blob();
console.log(output); // Blob { size: 6, type: "" }

Attaches a callback for only the rejection of the Promise.

The callback to execute when the Promise is rejected.

A Promise for the completion of the callback.

Change the current working directory of the shell.

The new working directory

Set environment variables for the shell.

The new environment variables

await $`echo $FOO`.env({ ...process.env, FOO: "LOL!" })
expect(stdout.toString()).toBe("LOL!");

Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.

The callback to execute when the Promise is settled (fulfilled or rejected).

A Promise for the completion of the callback.

Read from stdout as a JSON object

Automatically calls quiet

A promise that resolves with stdout as a JSON object

const output = await $`echo '{"hello": 123}'`.json();
console.log(output); // { hello: 123 }

Read from stdout as a string, line by line

Automatically calls quiet to disable echoing to stdout.

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.

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.

Whether to suppress output. Defaults to true.

Read from stdout as a string.

Automatically calls quiet to disable echoing to stdout.

The encoding to use when decoding the output

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"

Attaches callbacks for the resolution and/or rejection of the Promise.

The callback to execute when the Promise is resolved.

The callback to execute when the Promise is rejected.

A Promise for the completion of which ever callback is executed.

Configure whether or not the shell should throw an exception on non-zero exit codes.

By default, this is configured to true.

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.

An array of Promises.

A new Promise.

Creates a Promise that is resolved with an array of results when all of the provided Promises resolve or reject.

An array of Promises.

A new Promise.

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.

An array or iterable of Promises.

A new Promise.

Creates a Promise that is resolved or rejected when any of the provided Promises are resolved or rejected.

An array of Promises.

A new Promise.

Creates a new rejected promise for the provided reason.

The reason the promise was rejected.

A new rejected Promise.

Creates a new resolved promise for the provided value.

A promise.

A promise whose internal state matches the provided promise.

Try to run a function and return the result. If the function throws, return the result of the catch function.

The function to run

The arguments to pass to the function. This is similar to setTimeout and avoids the extra closure.

The result of the function or the result of the catch function

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!"