---
title: CLI Reference
description: Turborepo is a high-performance build system for JavaScript and TypeScript codebases.
---

import Callout from '../../../components/Callout'

# Command-Line Reference

After [installing the `turbo`](../getting-started) package (or cloning a starter), you can start using Turborepo's command line interface (CLI) `turbo` to do all kinds of awesomeness in your monorepo.

## Option Syntax

Options can be passed to `turbo` in different ways. Options that require a value can be passed with an equals sign:

```sh
--<option>=<value>
--<option>="<value with a space>"
```

Boolean options can be enabled as follows:

```sh
--no<option>
--<option>=false
```

## Global Arguments

The following flags apply to all commands.

#### `--color`

Forces the use of color even when the output stream is not considered to be a TTY terminal.
This can be used to enable turbo's color output for CI runners such as Github Actions which
have support for rendering color in their log output.

```sh
turbo run build --color
```

Alternatively, you can also enable color using the `FORCE_COLOR` environment variable (borrowed
from the [supports-color nodejs package](https://www.npmjs.com/package/supports-color)). Going
this route may also unlock some additional colored output from the actual tasks themselves if
they use `supports-color` to determine whether or not to output with colored output.

```sh
declare -x FORCE_COLOR=1
turbo run build
```

#### `--no-color`

Suppresses the use of color in the output when running turbo in an interactive / TTY session.

```sh
turbo run build --no-color
```

Alternatively, you can also suppress color using the `FORCE_COLOR` environment variable (borrowed
from the [supports-color nodejs package](https://www.npmjs.com/package/supports-color)).

```sh
declare -x FORCE_COLOR=0
turbo run build
```

## `turbo run <task>`

Run npm scripts across all packages in specified scope. Tasks must be specified in your `pipeline` configuration.

`turbo run <task1> <task2> [options] [-- <args passed to task1 and task2>]`

`turbo` can run multiple tasks, and any arguments following `--` will be passed through
to the tasks to be executed. Note that these additional arguments will _not_ be passed to
any additional tasks that are run due to dependencies from the [pipeline](/docs/reference/configuration#pipeline) configuration.

### Options

#### `--cache-dir`

`type: string`

Defaults to `./node_modules/.cache/turbo`. Specify local filesystem cache directory. Be sure to add this folder to your `.gitignore` if you change it from the default.

```sh
turbo run build --cache-dir="./my-cache"
```

#### `--concurrency`

`type: number | string`

Defaults to `10`. Set/limit the max concurrency of task execution. This must be an integer greater than or equal to `1` or a percentage value like `50%`. Use `1` to force serial (i.e. one task at a time) execution. Use `100%` to use all available logical processors. This option is ignored if the [`--parallel`](#--parallel) flag is also passed.

```sh
turbo run build --concurrency=50%
turbo run test --concurrency=1
```

#### `--continue`

Defaults to `false`. This flag tells `turbo` whether or not to continue with execution in the presence of an error (i.e. non-zero exit code from a task).
By default, specifying the `--parallel` flag will automatically set `--continue` to `true` unless explicitly set to `false`.
When `--continue` is `true`, `turbo` will exit with the highest exit code value encountered during execution.

```sh
turbo run build --continue
```

#### `--cwd`

Set the working directory of the command.

```sh
turbo run build --cwd=./somewhere/else
```

#### `--deps`

<Callout type="error">
  `--deps` is deprecated in `1.2.x`. Please use [`--filter`](/docs/core-concepts/filtering#include-dependents-of-matched-packages) instead.
</Callout>

Defaults to `true`. Include dependent packages/apps consumers in the execution.

```sh
turbo run build --deps
turbo run build --no-deps
```

**Example**

Let's say you have packages A, B, C, and D where A depends on B and C depends on D. You run `turbo run build` for the first time and everything is built and cached. Then, you change a line of code in B. With the `--deps` flag on, running `turbo run build` will execute `build` in B and then A, but not in C and D because they are not impacted by the change. If you were to run `turbo run build --no-deps` instead, turbo will only run `build` in B.

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

Instead of executing tasks, display details about the affected packages and tasks that would be run.
Specify `--dry=json` to get the output in JSON format.

Task details include:

- `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
- `directory`: The directory where the task will be run
- `command`: The actual command used to run the task
- `outputs`: Location of outputs from the task that will cached
- `logFile`: Location of the log file for the task run
- `dependencies`: Tasks that must run before this task
- `dependents`: Tasks that must be run after this task

#### `--filter`

`type: string[]`

Specify combinations of package(s)/apps, directories, and git commits to act as entrypoints
for execution.

Multiple filters can be combined to select distinct sets of targets. Additionally, filters
can also exclude targets. A target that matches any filter and is not explicitly excluded will
be in the final entrypoint selection.

For more detailed information about the `--filter` flag and filtering, refer to the [dedicated page in our documentation](/docs/core-concepts/filtering)

```sh
turbo run build --filter=my-pkg
turbo run test --filter=...^@scope/my-lib
turbo run build --filter=./apps/* --filter=!./apps/admin
```

#### `--graph`

This command will generate an svg, png, jpg, pdf, json, html, or [other supported output formats](https://graphviz.org/doc/info/output.html) of the current task graph.
The output file format defaults to jpg, but can be controlled by specifying the filename's extension.

If Graphviz is not installed, or no filename is provided, this command prints the dot graph to `stdout`.

```sh
turbo run build --graph
turbo run build test lint --graph=my-graph.svg
turbo run build test lint --graph=my-json-graph.json
turbo run build test lint --graph=my-graph.pdf
turbo run build test lint --graph=my-graph.png
turbo run build test lint --graph=my-graph.html
```

<Callout type="info">
  **Known Bug**: All possible pipeline task nodes will be added to the
  graph at the moment, even if that pipeline task does not actually exist in a
  given package. This has no impact on execution, it means that 1) the terminal output may overstate the number of packages in which a task is running and 2) your dot viz graph may contain additional nodes that represents tasks that do not exist.
</Callout>

#### `--force`

Ignore existing cached artifacts and forcibly re-execute all tasks (overwriting artifacts that overlap)

```sh
turbo run build --force
```

The same behavior also be set via the `TURBO_FORCE=true` environment variable.

#### `--global-deps`

Specify glob of global filesystem dependencies to be hashed. Useful for .env and files in the root directory that impact multiple packages/apps.
Can be specified multiple times.

```sh
turbo run build --global-deps=".env.*" --global-deps=".eslintrc" --global-deps="jest.config.js"
```

You can also specify these in your `turbo` configuration as `globalDependencies` key.

#### `--ignore`

`type: string[]`

Ignore **files or directories** from impacting scope. Uses glob patterns via [`multimatch`](https://github.com/sindresorhus/multimatch) under the hood.

```
turbo run build --ignore="apps/**/*"
turbo run build --ignore="packages/**/*"
turbo run build --ignore="packages/**/*" --ignore="\!/packages/not-this-one/**/*"
```

##### How multiple patterns work

Positive patterns (e.g. `foo` or `*`) add to the results, while negative patterns (e.g. `!foo`) subtract from the results.

Therefore a lone negation (e.g. `['!foo']`) will never match anything – use `['*', '!foo']` instead.

##### Globbing patterns

Just a quick overview.

- `*` matches any number of characters, but not `/`
- `?` matches a single character, but not `/`
- `**` matches any number of characters, including `/`, as long as it's the only thing in a path part
- `{}` allows for a comma-separated list of "or" expressions
- `!` at the beginning of a pattern will negate the match

#### `--include-dependencies`

<Callout type="error">
  `--include-dependencies` is deprecated in `1.2.x`. Please use [`--filter`](/docs/core-concepts/filtering#include-dependencies-of-matched-packages) instead.
</Callout>

Default `false`. When `true`, `turbo` will add any packages that the packages in the current execution _depend_ on (i.e. those declared in `dependencies` or `devDependencies`).

This is useful when using `--filter` in CI as it guarantees that every dependency needed for the execution is actually executed.

#### `--no-cache`

Default `false`. Do not cache results of the task. This is useful for watch commands like `next dev` or `react-scripts start`.

```shell
turbo run build --no-cache
turbo run dev --parallel --no-cache
```

#### `--output-logs`

`type: string`

Defaults to "outputMode" for the task in `turbo.json`. Set type of process output logging. Use `full` to show all output. Use `hash-only` to show only turbo-computed task hashes. Use `new-only` to show only new output with only hashes for cached tasks. Use `none` to hide process output.

```shell
turbo run build --output-logs=full
turbo run build --output-logs=new-only
```

#### `--only`

Default `false`. Restricts execution to only include specified tasks. This is very similar to how how `lerna` or `pnpm` run tasks by default.

Given this pipeline in `turbo.json`:

```json
{
  "$schema": "https://turborepo.org/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": [
        "^build"
      ]
    },
    "test": {
      "dependsOn": [
        "^build"
      ]
    }
  }
}
```

```shell
turbo run test --only
```

Will execute _only_ the `test` tasks in each package. It will not `build`.

#### `--parallel`

Default `false`. Run commands in parallel across packages and apps and ignore the dependency graph. This is useful for developing with live reloading.

```sh
turbo run lint --parallel --no-cache
turbo run dev --parallel --no-cache
```

#### `--remote-only`

Default `false`. Ignore the local filesystem cache for all tasks. Only allow reading and caching artifacts using the remote cache.

```shell
turbo run build --remote-only
```

The same behavior can also be set via the `TURBO_REMOTE_ONLY=true` environment variable.

#### `--scope`

<Callout type="error">
  `--scope` is deprecated in `1.2.x`. Please use [`--filter`](/docs/core-concepts/filtering#filter-by-package) instead.
</Callout>

`type: string[]`

Specify/filter package(s)/apps to act as entry points for execution. Globs against `package.json` `name` field (and not the file system.)

```sh
turbo run lint --scope="@example/**"
turbo run dev --parallel --scope="@example/a" --scope="@example/b" --no-cache --no-deps
```

#### `--serial`

**Deprecated in v0.5.3:** Use [`--concurrency=1`](#--concurrency) instead.

Executes all tasks serially (i.e. one-at-a-time).

```sh
turbo run build --serial
```

#### `--since`

<Callout type="error">
  `--since` is deprecated in `1.2.x`. Please use [`--filter`](/docs/core-concepts/filtering#filter-by-changed-packages) instead.
</Callout>

Filter execution based on which packages have changed since a merge-base.

```
turbo run build --since=origin/main
```

<Callout type="info">
  **Important**: This uses the `git diff ${target_branch}...` mechanism to
  identify which packages have changed. There is an assumption that all the
  input files for a package exist inside their respective package/app folders.
</Callout>

#### `--token`

A bearer token for remote caching. Useful for running in non-interactive shells (e.g. CI/CD) in combination with `--team` flags.

```sh
turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx
```

You can also set the value of the current token by setting an environment variable named `TURBO_TOKEN`. The flag will take precedence over the environment variable if both are present.

If you're using Remote Caching on Vercel, and your building your project on Vercel, this environment variable and flag are not needed because they are automatically set for you. If you’re using Remote Caching on Vercel, but building in another CI provider like CircleCI or GitHub Actions, you can use a Vercel Personal Access Token as your `—token` or `TURBO_TOKEN`. If you are using a custom Remote Cache, this value will be used to send an HTTP Bearer token with requests to your custom Remote Cache.

#### `--team`

The slug of the remote cache team. Useful for running in non-interactive shells in combination with `--token` and `--team` flags.

```sh
turbo run build --team=my-team
turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx
```

You can also set the value of the current team by setting an environment variable named `TURBO_TEAM`. The flag will take precedence over the environment variable if both are present.

#### `--preflight`

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

```sh
turbo run build --preflight
```

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

#### `--trace`

`type: string`

To view CPU trace, outputs the trace to the given file, use `go tool trace [file]`.

<Callout>
  **Important**: The trace viewer doesn't work under Windows Subsystem for Linux.
</Callout>

```sh
turbo run build --trace="<trace-file-name>"
```

#### `--heap`

`type: string`

To view heap trace, outputs the trace to the given file, use `go tool pprof [file]` and type `top`. You can also drop it into [speedscope](https://speedscope.app) and use the `left heavy` or `sandwich` view modes.

```sh
turbo run build --heap="<heap-file-name>"
```

#### `--cpuprofile`

`type: string`

To view CPU profile, outputs the profile to the given file, drop the file into [speedscope](https://speedscope.app).

<Callout>
  **Important**: The CPU profiler doesn't work under
  Windows Subsystem for Linux. The profiler has to be built
  for native Windows and run using the command prompt instead.
</Callout>

```sh
turbo run build --cpuprofile="<cpu-profile-file-name>"
```

#### `-v`, `-vv`, `-vvv`

To specify log level, use `-v` for `Info`, `-vv` for `Debug` and `-vvv` for `Trace` flags.

```sh
turbo run build -v
turbo run build -vv
turbo run build -vvv
```

## `turbo prune --scope=<target>`

Generate a sparse/partial monorepo with a pruned lockfile for a target package.

<Callout>
  This command is not yet implemented for `npm` or `pnpm`.
</Callout>

This command will generate folder called `out` with the following inside of it:

- The full source code of all internal packages that are needed to build the target
- A new pruned lockfile that only contains the pruned subset of the original root lockfile with the dependencies that are actually used by the packages in the pruned workspace.
- A copy of the root `package.json`

```
.                                 # Folder full source code for all package needed to build the target
├── package.json                  # The root `package.json`
├── packages
│   ├── ui
│   │   ├── package.json
│   │   ├── src
│   │   │   └── index.tsx
│   │   └── tsconfig.json
│   ├── shared
│   │   ├── package.json
│   │   ├── src
│   │   │   ├── __tests__
│   │   │   │   ├── sum.test.ts
│   │   │   │   └── tsconfig.json
│   │   │   ├── index.ts
│   │   │   └── sum.ts
│   │   └── tsconfig.json
│   └── frontend
│       ├── next-env.d.ts
│       ├── next.config.js
│       ├── package.json
│       ├── src
│       │   └── pages
│       │       └── index.tsx
│       └── tsconfig.json
└── yarn.lock                            # The pruned lockfile for all targets in the subworkspace
```

### Options

#### `--docker`

`type: boolean`

Default to `false`. Passing this flag will alter the outputted folder with the pruned workspace to make it easier to use with [Docker best practices / layer caching](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/).

With the `--docker` flag. The `prune` command will generate folder called `out` with the following inside of it:

- A folder `json` with the pruned workspace's `package.json`s
- A folder `full` with the pruned workspace's full source code, but only including the internal packages that are needed to build the target.
- A new pruned lockfile that only contains the pruned subset of the original root lockfile with the dependencies that are actually used by the packages in the pruned workspace.

```
.
├── full                                # Folder full source code for all package needed to build the target
│   ├── package.json
│   └── packages
│       ├── ui
│       │   ├── package.json
│       │   ├── src
│       │   │   └── index.tsx
│       │   └── tsconfig.json
│       ├── shared
│       │   ├── package.json
│       │   ├── src
│       │   │   ├── __tests__
│       │   │   │   ├── sum.test.ts
│       │   │   │   └── tsconfig.json
│       │   │   ├── index.ts
│       │   │   └── sum.ts
│       │   └── tsconfig.json
│       └── frontend
│           ├── next-env.d.ts
│           ├── next.config.js
│           ├── package.json
│           ├── src
│           │   └── pages
│           │       └── index.tsx
│           └── tsconfig.json
├── json                                # Folder containing just package.jsons for all targets in the subworkspace
│   ├── package.json
│   └── packages
│       ├── ui
│       │   └── package.json
│       ├── shared
│       │   └── package.json
│       └── frontend
│           └── package.json
└── yarn.lock                           # The pruned lockfile for all targets in the subworkspace
```

## `turbo login`

Connect machine to your Remote Cache provider. The default provider is [Vercel](https://vercel.com).

### Options

#### `--url`

`type: string`

Defaults to `https://vercel.com`.

#### `--api`

`type: string`

Defaults to `https://vercel.com/api`.

#### `--sso-team`

`type: string`

Connect to an sso-enabled Vercel team by providing your Team slug.

```
turbo login --sso-team=<team-slug>
```

## `turbo logout`

Logs you out of your Vercel account.

## `turbo link`

Link the current directory to Remote Cache scope. The selected owner (either a user or and organization) will be able to share [cache artifacts](../core-concepts/caching) through [Remote Caching](../core-concepts/remote-caching).
You should run this command from the root of your monorepo.

### Options

#### `--api`

`type: string`

Defaults to `https://api.vercel.com`

## `turbo unlink`

Unlink the current directory from the Remote Cache.

## `turbo bin`

Get the path to the Turbo binary.
