---
title: Workspace scripts
description: Named commands in the scripts key, run with `melos run` or as lifecycle hooks.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://melos.invertase.dev/llms.txt
> Use this file to discover all available pages before exploring further.

Run workspace scripts with `melos run <name>` or `melos <name>`. Melos also
runs them as lifecycle hooks for some commands.

Remember, the scripts go in the `scripts` section under the `melos` section in
the root `pubspec.yaml` file. For readability the `melos` section is omitted in
all following examples except for the first one.

With the simple syntax, only the name of the script and the command to execute
needs to be specified:

```yaml
melos:
  scripts:
    hello: echo 'Hello World'
```

The extends syntax allows for a more complex configuration of a script:

```yaml
scripts:
  hello:
    description: Greet the world
    run: echo "$GREETING World"
    env:
      GREETING: 'Hey'
```

## Shell

Scripts run in a shell. On Windows the shell is `cmd.exe` and on all other
platforms it is `sh`.

Variables defined in a script's `env` block (as well as the injected `MELOS_*`
variables) can be referenced with `$GREETING`, `${GREETING}`, or `%GREETING%`.
Use `$GREETING` or `${GREETING}` for cross-platform scripts.

On `sh` (macOS, Linux) the shell expands `$GREETING` and `${GREETING}`. Single
quotes prevent expansion (`echo '$GREETING'` prints `$GREETING` literally), and
double quotes allow it. Values stay data, so an `env` value with `&` or `|` does
not alter the command.

On Windows, Melos hands the command to `cmd.exe` through an intermediate
environment variable. `cmd` expands that variable only once, so Melos
substitutes the value for the reference. Expansion happens regardless of
quoting. The usual caveats for `cmd.exe` around special characters in values
apply.

If multiple commands are being executed in a script and you want Melos to stop
after a command fails, connect the commands with `&&`:

```yaml
scripts:
  prepare: melos bootstrap && melos run build
```

## Script name

Each script is identified by its key in the `scripts` map, which must be
unique. There is no separate `name` field.

## description

A short description, shown when using `melos run` with no argument.

## run

The command to execute.

## stdio

Controls how the script's process is connected to Melos input and output
streams. It accepts one of these values:

- `pipe` (default). Melos captures the script's `stdout` and `stderr` so it can
  prefix the output with the script name. The script's `stdin` is not connected.
- `inherit`. The script inherits Melos `stdin`, `stdout`, and `stderr`
  directly, giving it a real terminal (TTY). Use this for interactive commands
  that need a controlling terminal. Examples include `tmux attach`, `vim`,
  `less`, and hot-reload handlers in `flutter run` or `dart_frog dev`. In this
  mode Melos does not prefix the script's output.

```yaml
scripts:
  attach:
    run: tmux attach -t my_session
    stdio: inherit
```

`stdio: inherit` runs one foreground process on your terminal. Do not combine it
with [`exec`](/configuration/scripts#exec) (which runs the script across multiple
packages) or [`steps`](/configuration/scripts#steps) (which run inside a shared
shell). Set `stdio: inherit` on the individual scripts referenced from `steps`
instead.

## steps

Steps enables the combination of multiple scripts within a single script
definition for complex workflows. In the following example, `pre-commit` runs
`echo 'hello world'`, then formats the workspace, then runs Dart tests.

```yaml
scripts:
  pre-commit:
    description: pre-commit git hook script
    steps:
      - echo 'hello world'
      - format --output none --set-exit-if-changed
      - dart test --fail-fast .
```

Options related to `exec`, such as `concurrency`, and `packageFilters` cannot be
set on `steps`. Set them on the scripts that a step calls.

## dependsOn

The names of the scripts that have to run successfully before the script runs.
In the following example, `melos run test` first runs `generate`, and only runs
the tests if `generate` succeeded.

```yaml
scripts:
  generate:
    exec: dart run build_runner build

  test:
    exec: dart test
    dependsOn:
      - generate
```

The dependencies form a graph, which is more flexible than a sequential list of
[`steps`](/configuration/scripts#steps):

- The scripts that a script depends on can depend on other scripts themselves.
  All of them run before the requested script, each one after the scripts that
  it depends on.
- A script that multiple scripts depend on only runs once when the dependencies
  of the requested script are resolved. A script that is called from
  [`steps`](/configuration/scripts#steps) resolves its own dependencies, so a
  dependency that is shared between multiple steps runs once for each of them.
- If one of the scripts fails, the scripts that come after it do not run.
- A script can consist of only `dependsOn`, without `run`, `exec`, or `steps`,
  to group other scripts under a single name. The `env` and `packageFilters` of
  such a script are not applied to the scripts that it depends on.

```yaml
scripts:
  generate: dart run tool/generate.dart
  build:
    run: dart run tool/build.dart
    dependsOn:
      - generate
  test:
    exec: dart test
    dependsOn:
      - generate
  # Runs generate, build, and test, with generate only running once.
  verify:
    dependsOn:
      - build
      - test
```

Extra arguments that are passed to `melos run` are only passed to the requested
script, not to the scripts that it depends on. Package filters that are passed
on the command line, such as `--scope`, apply to all of the scripts. If no
package matches its filters, Melos skips a depended-on script with a warning.
That script has nothing to do for the selected packages.
[Private](/configuration/scripts#private) scripts can be used as dependencies.

Melos reports an error if a script depends on a script that does not exist, or
if the dependencies form a cycle. `dependsOn` is not supported for
[hooks](/configuration/scripts#hooks).

## exec

Execute a script in multiple packages through `melos exec`.

`run` and `exec` are mutually exclusive: a script either runs once in the
workspace root with [`run`](/configuration/scripts#run), or across multiple
packages with `exec`.

When using the default options for `melos exec`, specify the command directly as
the value of `exec`:

```yaml
scripts:
  hello:
    exec: echo 'Hello $(dirname $PWD)'
```

If you need to provide options for the `exec` command, turn `exec` into an object
and specify the command with the `command` key alongside the options:

```yaml
scripts:
  hello:
    exec:
      command: echo 'Hello $(dirname $PWD)'
      concurrency: 1
```

<Warning>
  Prior to Melos 8.0.0, the command was specified in `run` and the options in
  `exec`. This is no longer supported. Move the command into `exec` under the
  `command` key. For more information, see the
  [migration guide](/migration#configure-exec-scripts).
</Warning>

For more information about filtering packages, see
[`packageFilters`](/configuration/scripts#packagefilters).

### command

The command to execute in each package. Required when `exec` is an object.

### concurrency

Defines the maximum concurrency value, that is, the maximum number of packages
that the script runs concurrently at any given time. By default, this value is
set to the number of processors available on the underlying machine.

### failFast

Whether `exec` should fail fast and not execute the script in further packages
if the script fails in an individual package. Defaults to `false`.

### orderDependents

Whether `exec` should order the execution of the script in multiple packages
based on the dependency graph of the packages. The script runs in leaf packages
first and then in packages that depend on them and so on. This is useful for
example, for a script that generates code in multiple packages, which depend on
each other. Defaults to `false`.

### groupLogs

Whether Melos buffers package output and prints it per package after every
package finishes, instead of streaming and interleaving as the packages run. The
output of packages in which the script failed is printed last. Defaults to
`false`.

As with the command line flag, this only has an effect when the script runs in
more than one package with a [`concurrency`](#concurrency) greater than 1. With
`concurrency: 1` it is a no-op.

For more information, see
[`melos exec --group-logs`](/reference/commands/exec#--group-logs).

### sources

A list of globs, relative to the root of each package, that match the files the
result of the script depends on. Melos skips the script in packages where none
of the matching files, including workspace dependency files, changed after the
script last succeeded there.

```yaml
melos:
  scripts:
    generate:
      exec:
        command: dart run build_runner build
        orderDependents: true
        sources:
          - lib/**.dart
          - pubspec.yaml
```

A script that generates files that match the sources, like the `generate`
example, also specifies [`orderDependents`](#orderdependents). Scripts that do
not change the sources, such as running tests, do not need it.

Use [`melos run --run-unchanged`](/reference/commands/run#--run-unchanged) to run the
script in every package regardless, or
[`melos run --ignore-sources`](/reference/commands/run#--ignore-sources) to turn off the
checksums completely.

For more information, see
[`melos exec --sources`](/reference/commands/exec#--sources).

## env

A map of environment variables that Melos passes to the executed command.

## packageFilters

Selects the packages a script applies to. When running a script that uses
`packageFilters`, you are prompted to select one of the matching packages, or
all of them. Use the [`--no-select`](/reference/commands/run#--no-select) option to skip
the prompt and select all matching packages.

For more information about supported filters, see [global options](/filters).

<Warning>
  The filter names in `packageFilters` are camel cased. For example, for the
  equivalent of the command line option `--file-exists` use `fileExists`.
</Warning>

### With `exec`

For an [`exec`](/configuration/scripts#exec) script, the filters decide in which
packages the command is executed. The `hello_flutter` script is only executed in
Flutter packages:

```yaml
scripts:
  hello_flutter:
    exec: echo 'Hello $(dirname $PWD)'
    packageFilters:
      flutter: true
```

### With `run`

A [`run`](/configuration/scripts#run) script always executes once, in the
workspace root. `packageFilters` does not change that. What it does is pass the
selected packages to the script through the
[`MELOS_PACKAGES`](/environment-variables#melos_packages) environment variable,
which scopes any `melos` command the script itself invokes.

This is useful when the script wraps a Melos command:

```yaml
scripts:
  analyze_with_lib:
    run: melos exec -- dart analyze
    packageFilters:
      dirExists:
        - lib
```

Selecting a package in the prompt scopes the nested `melos exec`, so
`dart analyze` runs in that package.

<Warning>
  If the command is not a `melos` command, nothing reads `MELOS_PACKAGES`, so
  the filters have no effect beyond the prompt.
</Warning>

This script always runs `dart analyze` once in the workspace root, whichever
package is selected in the prompt:

```yaml
scripts:
  analyze:
    run: dart analyze
    packageFilters:
      dirExists:
        - lib
```

To analyze each package individually, use
[`exec`](/configuration/scripts#exec) instead of `run`.

## private

This option allows you to mark scripts as `private`.
Private scripts cannot be executed directly and are hidden from the command prompt.

They can only be referenced as `steps` within other scripts, or in the
[`dependsOn`](/configuration/scripts#dependson) of other scripts.

If you use the `--include-private` flag, this restriction is ignored.

### groups

Defines one or more groups for the specified script.
Scripts can be organized into logical groups, which can later be targeted or filtered
using the `--group` option when running commands. This is useful for hiding or executing
only scripts that belong to certain groups.


---

## Hooks

Certain Melos commands support running scripts before and after the command is
executed, as well as at other interesting points in the command's execution.

All commands that support hooks, support at least the `pre` and `post` hook.

Hooks are configured in the `hooks` section of a command's configuration in the
root `pubspec.yaml` file.

```yaml
melos:
  command:
    bootstrap:
      hooks:
        pre: echo "bootstrap command is running..."
        post: echo "bootstrap command is done"
```

The following Melos commands support hooks:

- [`bootstrap`](/reference/commands/bootstrap)
- [`clean`](/reference/commands/clean)
- [`version`](/reference/commands/version)
- [`publish`](/reference/commands/publish)

## Override built-in commands

Custom scripts can override Melos built-in commands. When a custom script has
the same name as a built-in command, the custom script takes precedence. This
allows you to customize the behavior of built-in commands to match your
workspace needs.

For example, you can override the built-in `format` command:

```yaml
scripts:
  format: dart run custom_formatter
```

With this configuration, both `melos format` and `melos run format` run your
custom format script instead of the built-in format command.
