---
title: run
description: API reference for the `turbo run` command
---

import { Callout } from '#components/callout';

Run tasks specified in `turbo.json`.

```bash title="Terminal"
turbo run [tasks] [options] [-- [args passed to tasks]]
```

- **[tasks]**: Turborepo can run one or many tasks at the same time. To run a task through `turbo`, it must be specified in `turbo.json`.
- **[options]**: Options are used to control the behavior of the `turbo run` command. Available flag options are described below.
- **[-- [args passed to tasks]]**: You may also pass arguments to the underlying scripts. Note that all arguments will be passed to all tasks that are named in the run command.

<Callout type="good-to-know">
  `turbo run` is aliased to `turbo`. `turbo run build lint check-types` is the
  same as `turbo build lint check-types`. We recommend [using `turbo run` in CI
  pipelines](/docs/crafting-your-repository/constructing-ci#use-turbo-run-in-ci)
  and `turbo` with [global `turbo`
  locally](/docs/getting-started/installation#global-installation) for ease of
  use.
</Callout>

If no tasks are provided, `turbo` will display what tasks are available for the packages in the repository.

```bash title="Terminal"
turbo run
```

## Options

### `--affected`

Filter to only packages that are affected by changes on the current branch.

```bash title="Terminal"
turbo run build lint test --affected
```

By default, the flag is equivalent to `--filter=...[main...HEAD]`. This considers changes between `main` and `HEAD` from Git's perspective.

<Callout type="warn">
  The comparison requires everything between base and head to exist in the
  checkout. If the checkout is too shallow, then all packages will be considered
  changed.

For example, setting up Git to check out with `--filter=blob:none --depth=0` will ensure `--affected` has the right history to work correctly.

</Callout>

You can override the default base and head with their respective [System Environment Variables](/docs/reference/system-environment-variables).

```bash title="Terminal"
# Override Git comparison base
TURBO_SCM_BASE=development turbo run build --affected

# Override Git comparison head
TURBO_SCM_HEAD=your-branch turbo run build --affected
```

### `--cache <options>`

Default: `local:rw,remote:rw`

Specify caching sources for the run. Accepts a comma-separated list of options:

- `local`: Use the local filesystem cache
- `remote`: Use the Remote Cache

When a caching source is omitted, reading and writing are both disabled.

Cache sources use the following values:

- `rw`: Read and write
- `r`: Read only
- `w`: Write only
- None (`local:`) : Does not use cache. Equivalent to omitting the cache source option.

```bash title="Terminal"
# Read from and write to local cache. Only read from Remote Cache.
turbo run build --cache=local:rw,remote:r

# Only read from local cache. Read from and write to Remote Cache.
turbo run build --cache=local:r,remote:rw

# Read from and write to local cache. No Remote Cache activity.
turbo run build --cache=local:rw

# Do not use local cache. Only read from Remote Cache.
turbo run build --cache=local:,remote:r
```

### `--cache-dir <path>`

Default: `.turbo/cache`

Specify the filesystem cache directory.

```bash title="Terminal"
turbo run build --cache-dir="./my-cache"
```

<Callout type="warn">
  Ensure the directory is in your `.gitignore` when changing it.
</Callout>

The same behavior can also be set via the `TURBO_CACHE_DIR=example/path` system variable.

### `--concurrency <number | percentage>`

Default: `10`

Set/limit the maximum concurrency for task execution. Must be an integer greater than or equal to `1` or a percentage value like `50%`.

- Use `1` to force serial execution (one task at a time).
- Use `100%` to use all available logical processors.
- This option is ignored if the [`--parallel`](#--parallel) flag is also passed.

```bash title="Terminal"
turbo run build --concurrency=50%
turbo run test --concurrency=5
```

### `--continue[=<option>]`

Default: `never`

Specify how `turbo` should handle current and pending tasks in the presence of an error (e.g. non-zero exit code from a task).

- When `--continue=never` and an error occurs, `turbo` will cancel all tasks.
- When `--continue=dependencies-successful` and an error occurs, `turbo` will cancel dependent tasks. Tasks whose dependencies have succeeded will continue to run.
- When `--continue=always` and an error occurs, `turbo` will continue running all tasks, even those whose dependencies have failed.
- When `--continue` is specified without a value, it will default to `always`.

In all cases, `turbo` will exit with the highest exit code value encountered during execution.

```bash title="Terminal"
turbo run build --continue
```

### `--cwd <path>`

Default: Directory of root `turbo.json`

Set the working directory of the command.

```bash title="Terminal"
turbo run build --cwd=./somewhere/else/in/your/repo
```

### `--dangerously-disable-package-manager-check`

Turborepo uses your repository's lockfile to determine caching behavior, [Package Graphs](https://turborepo.com/docs/core-concepts/internal-packages), and more. Because of this, we use [the `packageManager` field](https://nodejs.org/api/packages.html#packagemanager) to help you stabilize your Turborepo.

To help with incremental migration or in situations where you cannot use the `packageManager` field, you may use `--dangerously-disable-package-manager-check` to opt out of this check and assume the risks of unstable lockfiles producing unpredictable behavior. When disabled, Turborepo will attempt a best-effort discovery of the intended package manager meant for the repository.

<Callout type="info">
  You may also opt out of this check using [configuration in
  `turbo.json`](/docs/reference/configuration#dangerouslydisablepacakgemanagercheck)
  or the
  [`TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK`](/docs/reference/system-environment-variables)
  environment variable for broader coverage.
</Callout>

### `--dry / --dry-run`

Instead of executing tasks, display details about the packages and tasks that would be run.

Specify `--dry=json` to get the output in JSON format.

Task details include useful information like (list is non-exhaustive):

| Field                        | Description                                                            |
| ---------------------------- | ---------------------------------------------------------------------- |
| `taskId`                     | ID for the task, in the format of `package-name#task-name`             |
| `task`                       | The name of the task to be executed                                    |
| `package`                    | The package in which to run the task                                   |
| `hash`                       | The hash of the task (used for caching)                                |
| `hashOfExternalDependencies` | The global hash                                                        |
| `command`                    | The command used to run the task                                       |
| `inputs`                     | List of file inputs considered for hashing                             |
| `outputs`                    | List of file outputs that were cached                                  |
| `dependencies`               | Tasks that must run **before** this task                               |
| `dependents`                 | Tasks that must run **after** this task                                |
| `environmentVariables`       | Lists of environment variables specified in `env` and `passThroughEnv` |

### `--env-mode <option>`

`type: string`

Controls the available environment variables in the task's runtime.

<Callout type="good-to-know">
  `PATH`, `SHELL`, and `SYSTEMROOT` are always available to the task.
</Callout>

| option                      | description                                                        |
| --------------------------- | ------------------------------------------------------------------ |
| [strict](#strict) (Default) | Only allow explicitly listed environment variables to be available |
| [loose](#loose)             | Allow **all** environment variables to be available                |

```bash title="Terminal"
turbo run build --env-mode=loose
```

The same behavior can also be set via the `TURBO_ENV_MODE=strict` system variable.

#### `strict`

Only environment variables specified in the following keys are
available to the task:

- [`env`](/docs/reference/configuration#env)
- [`passThroughEnv`](/docs/reference/configuration#passthroughenv)
- [`globalEnv`](/docs/reference/configuration#globalenv)
- [`globalPassThroughEnv`](/docs/reference/configuration#globalpassthroughenv)

If Strict Mode is specified or inferred, **all** tasks are run in `strict` mode,
regardless of their configuration.

#### `loose`

All environment variables on the machine are made available to the task's runtime.

<Callout type="warn">
  This can be dangerous when environment variables are not accounted for in
  caching with the keys listed in `strict` above. You're much more likely to
  restore a version of your package with wrong environment variables from cache
  in `loose` mode.
</Callout>

### `--filter <string>`

Specify targets to execute from your repository's graph. Multiple filters can be combined to select distinct sets of targets.

Filters can be combined to create combinations of packages, directories, and git commits.

| Target type | Description                                                                                                                | Example                             |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| Package     | Select a package by its name in `package.json`.                                                                            | `turbo run build --filter=ui`       |
| Directory   | Specify directories to capture a list of packages to run tasks. **When used with other filters, must be wrapped in `{}`**. | `turbo run build --filter=./apps/*` |
| Git commits | Using Git specifiers, specify packages with source control changes. **Must be wrapped in `[]`**.                           | `turbo run build --filter=[HEAD^1]` |

<Callout type="good-to-know">`-F` is an alias for `--filter`.</Callout>

#### Microsyntaxes for filtering

- `!`: Negate targets from the selection.
- `...` using packages: Select all packages in the [Package Graph](/docs/core-concepts/package-and-task-graph#package-graph) relative to the target. Using `...` **before** the package name will select **dependents** of the target while using `...` **after** the package name will select **dependencies** of the target.
- `...` using Git commits: Select a range using `[<from commit>]...[<to commit>]`.
- `^`: Omit the target from the selection when using `...`.

For in-depth discussion and practical use cases of filtering, visit [the Running Tasks page](/docs/crafting-your-repository/running-tasks).

#### Using a task identifier

You can also run a specific task for a specific package in the format of `package-name#task-name`.

```bash title="Terminal"
turbo run web#lint
```

<Callout type="good-to-know">
  This will also run the task's dependencies. To run a task without its
  dependencies, use [the `--only` flag](#--only).
</Callout>

#### Advanced filtering examples

You can combine multiple filters to further refine your targets. Multiple filters are combined as a union, with negated filters removing packages from the result of the union.

```bash title="Terminal"
# Any packages in `apps` subdirectories that have changed since the last commit
turbo run build --filter={.apps/*}[HEAD^1]

# Any packages in `apps` subdirectories except ./apps/admin
turbo run build --filter=./apps/* --filter=!./apps/admin

# Run the build task for the docs and web packages
turbo run build --filter=docs --filter=web

# Build everything that depends on changes in branch 'my-feature'
turbo run build --filter=...[origin/my-feature]

# Build everything that depends on changes between two Git SHAs
turbo run build --filter=[a1b2c3d...e4f5g6h]

# Build '@acme/ui' if:
# - It or any of its dependencies have changed since the previous commit
turbo run build --filter=@acme/ui...[HEAD^1]

# Test each package that is:
# - In the '@acme' scope
# - Or, in the 'packages' directory
# - Or, changed since the previous commit
turbo run test --filter=@acme/*{./packages/*}[HEAD^1]
```

### `--force`

Ignore existing cached artifacts and re-execute all tasks.

<Callout type="good-to-know">
  `--force` will overwrite existing task caches.
</Callout>

```bash title="Terminal"
turbo run build --force
```

The same behavior can also be set via [the `TURBO_FORCE` environment variable](/docs/reference/system-environment-variables).

### `--framework-inference`

Default: `true`

Specify whether or not to do [Framework Inference](/docs/crafting-your-repository/using-environment-variables#framework-inference) for tasks.

When `false`, [automatic environment variable inclusion](/docs/crafting-your-repository/using-environment-variables#framework-inference) is disabled.

```bash title="Terminal"
turbo run build --framework-inference=false
```

### `--global-deps <file glob>`

Specify glob of global filesystem dependencies to be hashed. Useful for `.env` and files in the root directory that impact multiple packages.

```bash title="Terminal"
turbo run build --global-deps=".env"
turbo run build --global-deps=".env.*" --global-deps=".eslintrc" --global-deps="jest.config.ts"
```

<Callout type="info">
  We recommend specifying file globs that you'd like to include your hashes in
  [the `globalDependencies` key](/docs/reference/configuration#globaldeps) in
  `turbo.json` to make sure they are always accounted for.
</Callout>

### `--graph <file name>`

Default: `dot`

This command can output a graph file: `svg`, `png`, `jpg`, `pdf`, `json`, `html`, `mermaid`, or `dot`.

If [Graphviz](https://graphviz.org/) is not installed, or no filename is provided, this command prints the dot graph to `stdout`.

```bash title="Terminal"
turbo run build --graph
turbo run build test lint --graph=my-graph.svg
```

<Callout type="info">
  **Known Bug**: All possible task nodes will be added to the graph at the
  moment, even if that script does not actually exist in a given package. This
  has no impact on execution, but the graph may overstate the number of packages
  and tasks involved.
</Callout>

### `--log-order <option>`

Default: `auto`

Set the ordering for log output.

By default, `turbo` will use `grouped` logs in CI environments and `stream` logs everywhere else. This flag is not applicable when using [the terminal UI](https://turborepo.com/docs/reference/configuration#ui).

```bash title="Terminal"
turbo run build --log-order=stream
```

| Option    | Description                                 |
| --------- | ------------------------------------------- |
| `stream`  | Show output as soon as it is available      |
| `grouped` | Group output by task                        |
| `auto`    | `turbo` decides based on its own heuristics |

### `--log-prefix <option>`

Default: `auto`

Control the `<package>:<task>:` prefix for log lines produced when running tasks.

```bash title="Terminal"
turbo run dev --log-prefix=none
```

| Option | Description                                             |
| ------ | ------------------------------------------------------- |
| `task` | Force prepending the `<package>:<task>:` prefix to logs |
| `none` | No prefixes                                             |
| `auto` | `turbo` decides based on its own heuristics             |

### `--no-cache`

<Callout type="warn" title="Deprecated">
  This flag is deprecated and will be removed in a future major release. Please
  use the [`--cache`](#--cache-options) flag instead.
</Callout>

Default `false`

Do not cache results of the task.

```bash title="Terminal"
turbo run dev --no-cache
```

### `--daemon` and `--no-daemon`

`turbo` can run a background process to pre-calculate values used for determining work that needs to be done. This standalone process (daemon) is an optimization, and not required for proper functioning of `turbo`.

The default daemon usage is set for your repository using [the `daemon` field in `turbo.json`](/docs/reference/configuration#daemon). Passing `--daemon` requires `turbo` to use the standalone process, while `--no-daemon` instructs `turbo` to avoid using or creating the standalone process.

The same behavior can also be set via the `TURBO_DAEMON=true` system variable.

### `--output-logs <option>`

Default: `full`

Set type of output logging, overriding [`outputLogs`](/docs/reference/configuration#outputlogs) if it's defined in `turbo.json`.

```bash title="Terminal"
turbo run build --output-logs=errors-only
```

| Option        | Description                       |
| ------------- | --------------------------------- |
| `full`        | Displays all logs                 |
| `hash-only`   | Only show the hashes of the tasks |
| `new-only`    | Only show logs from cache misses  |
| `errors-only` | Only show logs from task failures |
| `none`        | Hides all task logs               |

### `--only`

Default: `false`

Restricts execution to include specified tasks only.

#### Example

Given this `turbo.json`:

```json title="./turbo.json"
{
  "$schema": "https://turborepo.com/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"]
    }
  }
}
```

```bash title="Terminal"
turbo run test --only
```

The command will _only_ execute the `test` tasks in each package. It will not run `build`.

Additionally, `--only` will only run tasks in specified packages, excluding dependencies. For example, `turbo run build --filter=web --only`, will **only** run the `build` script in the `web` package.

### `--parallel`

Default: `false`

Run commands in parallel across packages, ignoring the task dependency graph.

```bash title="Terminal"
turbo run lint --parallel
turbo run dev --parallel
```

<Callout type="info">
  The `--parallel` flag is typically used for long-running "dev" or "watch"
  tasks that don't exit. Starting in `turbo@1.7`, we recommend configuring these
  tasks using [`persistent`](/docs/reference/configuration#persistent) instead.
</Callout>

### `--preflight`

Only applicable when Remote Caching is configured. Enables sending a preflight request before every cache artifact and analytics request. The follow-up upload and download will follow redirects.

```bash title="Terminal"
turbo run build --preflight
```

The same behavior can also be set via the `TURBO_PREFLIGHT=true` system variable.

### `--profile`

Generates a trace of the run in Chrome Tracing format that you can use to analyze performance.

You must provide a verbosity flag (`-v`, `-vv`, or `-vvv`) with `--profile` to produce a trace.

```bash title="Terminal"
turbo run build --profile=profile.json -vvv
```

Profiles can be viewed in a tool like [Perfetto](https://ui.perfetto.dev/).

### `--remote-cache-timeout`

Default: `30`

Set the timeout for Remote Cache operations in seconds.

```bash title="Terminal"
turbo run build --remote-cache-timeout=60
```

### `--remote-only`

<Callout type="warn" title="Deprecated">
  This flag is deprecated and will be removed in a future major release. Please
  use the [`--cache`](#--cache-options) flag instead.
</Callout>

Default: `false`

Ignore the local filesystem cache for all tasks, using Remote Cache for reading and caching task outputs.

```bash title="Terminal"
turbo run build --remote-only
```

### `--summarize`

Generates a JSON file in `.turbo/runs` containing metadata about the run, including:

- Affected packages
- Executed tasks (including their timings and hashes)
- All the files included in the cached artifact

```bash title="Terminal"
turbo run build --summarize
```

This flag can be helpful for debugging to determine things like:

- How `turbo` interpreted your glob syntax for `inputs` and `outputs`
- What inputs changed between two task runs to produce a cache miss
- How task timings changed over time

<Callout type="info" title="Summaries viewer">
  While there is not a Turborepo-native Run Summaries UI viewer, we encourage
  you to use the community-built
  [https://turbo.nullvoxpopuli.com](https://turbo.nullvoxpopuli.com) if you
  would like to view your Run Summaries as a web view.
</Callout>

### `--token`

A bearer token for Remote Caching. Useful for running in non-interactive shells in combination with the `--team` flag.

```bash title="Terminal"
turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx
```

This value can also be set using [the `TURBO_TOKEN` system variable](/docs/reference/system-environment-variables). If both are present, the flag value will override the system variable.

<Callout type="good-to-know">
  If you are using [Vercel Remote
  Cache](https://vercel.com/docs/monorepos/remote-caching) and building your
  project on Vercel, you do not need to use this flag. This value will be
  automatically set for you.
</Callout>

### `--team`

The slug of the Remote Cache team. Useful for running in non-interactive shells in combination with the `--token` flag.

```bash title="Terminal"
turbo run build --team=my-team
turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx
```

This value can also be set using [the `TURBO_TEAM` system variable](/docs/reference/system-environment-variables). If both are present, the flag value will override the system variable.

### `--ui`

Specify the UI to use for output. Accepts `stream` or `tui`.

### `--verbosity`

To specify log level, use `--verbosity=<num>` or `-v, -vv, -vvv`.

| Level | Flag value      | Shorthand |
| ----- | --------------- | --------- |
| Info  | `--verbosity=1` | `-v`      |
| Debug | `--verbosity=2` | `-vv`     |
| Trace | `--verbosity=3` | `-vvv`    |

```bash title="Terminal"
turbo run build --verbosity=2
turbo run build -vvv
```
