class

$.ShellPromise

class ShellPromise

A shell command that runs once awaited, or once an output method like .text() or .json() is called.

const myShellPromise = $`echo "Hello, world!"`;
const result = await myShellPromise.text();
console.log(result); // "Hello, world!"
  • readonly [Symbol.toStringTag]: string

  • 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.

  • newCwd: string
    ): this;

    Change the current working directory of the shell.

    @param newCwd

    The new working directory

  • newEnv: undefined | Dict<string> | Record<string, undefined | string>
    ): this;

    Set environment variables for the shell.

    @param newEnv

    The new environment variables

    const { stdout } = await $`echo $FOO`.env({ ...process.env, FOO: "bun" });
console.log(stdout.toString()); // "bun\n"
  • 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 throws an exception on commands that return non-zero exit codes.

  • isQuiet?: boolean
    ): this;

    By default, the shell writes to the current process's stdout and stderr while also buffering that output.

    quiet() configures the shell to only buffer the output.

    @param isQuiet

    Whether to suppress output. Defaults to true

  • 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.

  • shouldThrow: boolean
    ): this;

    Configure whether 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>;

    Run a function and return a promise of its result. If the function throws, the returned promise rejects with the thrown error.

    @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

    A promise that resolves with the function's result

  • static withResolvers<T>(): { promise: Promise<T>; reject: (reason?: any) => void; resolve: (value?: T | PromiseLike<T>) => void };

    Create a deferred promise with its resolve and reject functions exposed, so code outside the promise can settle it.

    const { promise, resolve, reject } = Promise.withResolvers();

setTimeout(() => {
 resolve("Hello world!");
}, 1000);

await promise; // "Hello world!"