Skip to main content

Execa

Helper functions having to do with running commands in a Bash-like TypeScript script.

These functions are based upon the $ function from the execa library, but pass the stdout/stderr to the console (which is the default behavior of a Bash script).

Functions

$()

Same as execa() but using script-friendly default options.

When command is a template string, it includes both the file and its arguments.

$(options) can be used to return a new instance of this method but with different default options. Consecutive calls are merged to previous ones.

This is the preferred method when executing multiple commands in a script file.

Throws

ExecaError

Examples

import {$} from 'execa';

const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
$ node build.js
Building application...
Done building.
Running tests...
Error: the entrypoint is invalid.

$ NODE_DEBUG=execa node build.js
[00:57:44.581] [0] $ npm run build
[00:57:44.653] [0] Building application...
[00:57:44.653] [0] Done building.
[00:57:44.658] [0] ✔ (done in 78ms)
[00:57:44.658] [1] $ npm run test
[00:57:44.740] [1] Running tests...
[00:57:44.740] [1] Error: the entrypoint is invalid.
[00:57:44.747] [1] ✘ Command failed with exit code 1: npm run test
[00:57:44.747] [1] ✘ (done in 89ms)

$(options)

function $<NewOptionsType>(options): ExecaScriptMethod<object & NewOptionsType>

Same as execa() but using script-friendly default options.

When command is a template string, it includes both the file and its arguments.

$(options) can be used to return a new instance of this method but with different default options. Consecutive calls are merged to previous ones.

This is the preferred method when executing multiple commands in a script file.

Type Parameters
Type ParameterDefault type
NewOptionsType extends CommonOptionsobject
Parameters
ParameterType
optionsNewOptionsType
Returns

ExecaScriptMethod<object & NewOptionsType>

Throws

ExecaError

Examples
import {$} from 'execa';

const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
$ node build.js
Building application...
Done building.
Running tests...
Error: the entrypoint is invalid.

$ NODE_DEBUG=execa node build.js
[00:57:44.581] [0] $ npm run build
[00:57:44.653] [0] Building application...
[00:57:44.653] [0] Done building.
[00:57:44.658] [0] ✔ (done in 78ms)
[00:57:44.658] [1] $ npm run test
[00:57:44.740] [1] Running tests...
[00:57:44.740] [1] Error: the entrypoint is invalid.
[00:57:44.747] [1] ✘ Command failed with exit code 1: npm run test
[00:57:44.747] [1] ✘ (done in 89ms)
Defined in

node_modules/execa/types/methods/script.d.ts:53

$(templateString)

function $(...templateString): ResultPromise<object>

Same as execa() but using script-friendly default options.

When command is a template string, it includes both the file and its arguments.

$(options) can be used to return a new instance of this method but with different default options. Consecutive calls are merged to previous ones.

This is the preferred method when executing multiple commands in a script file.

Parameters
ParameterType
...templateStringreadonly [TemplateStringsArray, TemplateExpression]
Returns

ResultPromise<object>

Throws

ExecaError

Examples
import {$} from 'execa';

const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
$ node build.js
Building application...
Done building.
Running tests...
Error: the entrypoint is invalid.

$ NODE_DEBUG=execa node build.js
[00:57:44.581] [0] $ npm run build
[00:57:44.653] [0] Building application...
[00:57:44.653] [0] Done building.
[00:57:44.658] [0] ✔ (done in 78ms)
[00:57:44.658] [1] $ npm run test
[00:57:44.740] [1] Running tests...
[00:57:44.740] [1] Error: the entrypoint is invalid.
[00:57:44.747] [1] ✘ Command failed with exit code 1: npm run test
[00:57:44.747] [1] ✘ (done in 89ms)
Defined in

node_modules/execa/types/methods/script.d.ts:53

$(file, arguments, options)

function $<NewOptionsType>(
file,
arguments?,
options?): ResultPromise<StricterOptions<object & NewOptionsType, Options>>

Same as execa() but using script-friendly default options.

When command is a template string, it includes both the file and its arguments.

$(options) can be used to return a new instance of this method but with different default options. Consecutive calls are merged to previous ones.

This is the preferred method when executing multiple commands in a script file.

Type Parameters
Type ParameterDefault type
NewOptionsType extends Optionsobject
Parameters
ParameterType
filestring | URL
arguments?readonly string[]
options?NewOptionsType
Returns

ResultPromise<StricterOptions<object & NewOptionsType, Options>>

Throws

ExecaError

Examples
import {$} from 'execa';

const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
$ node build.js
Building application...
Done building.
Running tests...
Error: the entrypoint is invalid.

$ NODE_DEBUG=execa node build.js
[00:57:44.581] [0] $ npm run build
[00:57:44.653] [0] Building application...
[00:57:44.653] [0] Done building.
[00:57:44.658] [0] ✔ (done in 78ms)
[00:57:44.658] [1] $ npm run test
[00:57:44.740] [1] Running tests...
[00:57:44.740] [1] Error: the entrypoint is invalid.
[00:57:44.747] [1] ✘ Command failed with exit code 1: npm run test
[00:57:44.747] [1] ✘ (done in 89ms)
Defined in

node_modules/execa/types/methods/script.d.ts:53

$(file, options)

function $<NewOptionsType>(file, options?): ResultPromise<StricterOptions<object & NewOptionsType, Options>>

Same as execa() but using script-friendly default options.

When command is a template string, it includes both the file and its arguments.

$(options) can be used to return a new instance of this method but with different default options. Consecutive calls are merged to previous ones.

This is the preferred method when executing multiple commands in a script file.

Type Parameters
Type ParameterDefault type
NewOptionsType extends Optionsobject
Parameters
ParameterType
filestring | URL
options?NewOptionsType
Returns

ResultPromise<StricterOptions<object & NewOptionsType, Options>>

Throws

ExecaError

Examples
import {$} from 'execa';

const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
$ node build.js
Building application...
Done building.
Running tests...
Error: the entrypoint is invalid.

$ NODE_DEBUG=execa node build.js
[00:57:44.581] [0] $ npm run build
[00:57:44.653] [0] Building application...
[00:57:44.653] [0] Done building.
[00:57:44.658] [0] ✔ (done in 78ms)
[00:57:44.658] [1] $ npm run test
[00:57:44.740] [1] Running tests...
[00:57:44.740] [1] Error: the entrypoint is invalid.
[00:57:44.747] [1] ✘ Command failed with exit code 1: npm run test
[00:57:44.747] [1] ✘ (done in 89ms)
Defined in

node_modules/execa/types/methods/script.d.ts:53


$o()

function $o(templates, ...expressions): string

Helper function to run a command and grab the output. ("o" is short for "output".)

If an error occurs, the full JavaScript stack trace will be printed. Alternatively, if you expect this command to return a non-zero exit code, you can enclose this function in a try/catch block.

This is a wrapper around the $.sync function from execa. (The $.sync function automatically trims the stdout.)

Parameters

ParameterType
templatesTemplateStringsArray
...expressionsreadonly TemplateExpression[]

Returns

string

Defined in

packages/complete-node/src/functions/execa.ts:28


$q()

function $q(templates, ...expressions): Promise<Result>

A wrapper around the $ function from execa. ("q" is short for "quiet".) This is the same thing as the $ helper function, except the stdout/stderr is not passed through to the console.

If an error occurs, the full JavaScript stack trace will be printed. Alternatively, if you expect this command to return a non-zero exit code, you can enclose this function in a try/catch block.

Parameters

ParameterType
templatesTemplateStringsArray
...expressionsreadonly TemplateExpression[]

Returns

Promise<Result>

Defined in

packages/complete-node/src/functions/execa.ts:42


$s()

function $s(templates, ...expressions): Result

Alias for the $.sync function from execa.

Parameters

ParameterType
templatesTemplateStringsArray
...expressionsreadonly TemplateExpression[]

Returns

Result

Defined in

packages/complete-node/src/functions/execa.ts:53


$sq()

function $sq(templates, ...expressions): Result

A wrapper around the $.sync function from execa. ("sq" is short for "sync quiet".) This is the same thing as the $s helper function, except the stdout/stderr is not passed through to the console.

If an error occurs, the full JavaScript stack trace will be printed. Alternatively, if you expect this command to return a non-zero exit code, you can enclose this function in a try/catch block.

Parameters

ParameterType
templatesTemplateStringsArray
...expressionsreadonly TemplateExpression[]

Returns

Result

Defined in

packages/complete-node/src/functions/execa.ts:68