# @netlify/run-utils

> Utility for running commands inside Netlify Build

Latest version **7.1.0** (published 2026-07-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install @netlify/run-utils
pnpm add @netlify/run-utils
yarn add @netlify/run-utils
bun add @netlify/run-utils
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 7.1.0 |
| Published | 2026-07-17 |
| First published | 2020-01-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.12.0 |
| Dependencies | 1 |
| Unpacked size | 6.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 258 |
| Author | Netlify Inc. |
| Maintainers | netlify-bot, mikewen, youvalv, serhalp-netlify, mlgualtieri-gatsby |
| Keywords | nodejs, javascript, windows, macos, linux, shell, bash, build, terminal, deployment, es6, serverless, continuous-integration, continuous-delivery, ci, continuous-deployment, plugins, continuous-testing, netlify-plugin, netlify |

## Links

- npm: https://www.npmjs.com/package/@netlify/run-utils
- Repository: https://github.com/netlify/build
- Issues: https://github.com/netlify/build/issues
- npm.io page: https://npm.io/package/@netlify/run-utils

## Dependencies (1)

- [execa](https://npm.io/package/execa.md) ^8.0.0

## Alternatives

- [random-seedable](https://npm.io/package/random-seedable.md) — 27.9K weekly downloads
- [n2words](https://npm.io/package/n2words.md) — 22.2K weekly downloads
- [@stdlib/math-base-special-factorialln](https://npm.io/package/@stdlib/math-base-special-factorialln.md) — 5.7K weekly downloads
- [@stdlib/math-base-special-abs2](https://npm.io/package/@stdlib/math-base-special-abs2.md) — 1.7K weekly downloads
- [commons-math-interpolation](https://npm.io/package/commons-math-interpolation.md) — 1.4K weekly downloads

## Recent versions

- 7.1.0 (latest) — 2026-07-17
- 4.0.3-rc (rc) — 2022-09-23
- 7.0.0 — 2026-06-16
- 6.0.3 — 2026-02-25
- 6.0.2 — 2025-05-29
- 6.0.1 — 2025-05-20
- 6.0.0 — 2025-05-14
- 5.2.0 — 2024-12-11
- 5.1.1 — 2023-06-05
- 5.1.0 — 2022-12-13
- 5.0.2 — 2022-11-17
- 5.0.1 — 2022-10-18
- 5.0.0 — 2022-10-11
- 4.0.2 — 2022-09-26
- 4.0.2-rc — 2022-09-23
- … 17 more at https://npm.io/package/@netlify/run-utils/versions

## README

[![Coverage Status](https://codecov.io/gh/netlify/build/branch/main/graph/badge.svg)](https://codecov.io/gh/netlify/build)
[![Build](https://github.com/netlify/build/workflows/Build/badge.svg)](https://github.com/netlify/build/actions)

Utility for running commands inside Netlify Build

Currently, there is just one utility, `run`, which is a thin wrapper over `execa` defaulting to
`{ preferLocal: true, stdio: 'inherit' }`.

# Examples

```js
// Runs `eslint src/ test/` and prints the result
// Either local or global binaries can be run
const exampleNetlifyPlugin = {
  async onBuild({ utils: { run } }) {
    await run('eslint', ['src/', 'test/'])
  },
}
```

```js
// Same but with a more convenient syntax
const exampleNetlifyPlugin = {
  async onBuild({ utils: { run } }) {
    await run.command('eslint src/ test/')
  },
}
```

```js
// Retrieve command's output and exit code as variables
const exampleNetlifyPlugin = {
  async onBuild({ utils: { run } }) {
    const { stdout, stderr, exitCode } = await run('eslint', ['src/', 'test/'])
    console.log({ stdout, stderr, exitCode })
  },
}
```

```js
// Streaming mode
const exampleNetlifyPlugin = {
  onBuild({ utils: { run } }) {
    const { stdout } = run('eslint', ['src/', 'test/'])
    stdout.pipe(fs.createWriteStream('stdout.txt'))
  },
}
```

```js
// If the command exit code is not 0 or was terminated by a signal, an error
// is thrown with failure information
const exampleNetlifyPlugin = {
  async onBuild({ utils: { run } }) {
    try {
      await run('eslint', ['does_not_exist'])
    } catch (error) {
      console.error(error)
    }
  },
}
```

```js
// Pass environment variables
const exampleNetlifyPlugin = {
  async onBuild({ utils: { run } }) {
    await run('eslint', ['src/', 'test/'], { env: { TEST: 'true' } })
  },
}
```

# API

## run(file, arguments, options?)

Execute a command/file.

## run.command(command, options?)

Same as [`run()`](#runfile-arguments-options) except both file and arguments are specified in a single `command` string.
For example, `run('echo', ['netlify'])` is the same as `run.command('echo netlify')`.

If the file or an argument contains spaces, they must be escaped with backslashes. This matters especially if `command`
is not a constant but a variable, for example with `__dirname` or `process.cwd()`. Except for spaces, no
escaping/quoting is needed.

---
_Source: https://npm.io/package/@netlify/run-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._