Command-Line Reference

After installing the turbo 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:

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

Boolean options can be enabled as follows:

--no<option>
--<option>=false

turbo run <task1> <task2>

Run NPM scripts across all packages in specified scope. Tasks must be specified in your 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.

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

--concurrency

type: number

Defaults to 10. Set/limit the max concurrency of task execution. This must be an integer greater than or equal to 1. Use 1 to force serial (i.e. one task at a time) execution. This option is ignored if the --parallel flag is also passed.

turbo run build --concurrency=10
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.

turbo run build --continue

--cwd

Set the working directory of the command.

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

--deps

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

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.

--graph

type: string

If Graphviz is installed, this command will generate an svg, png, jpg, pdf, json, html, or other supported output formats of the current task graph. The output file format can be controlled with the filename's extension if it is specified. If a filename is not specified, graph-<timestamp>.jpg is outputted.

If Graphviz is not installed, this command prints the dot graph to stdout.

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

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:

  • the terminal output may overstate the number of packages in which a task is running.
  • your dot viz graph may contain additional nodes that represents tasks that do not exist.

--force

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

turbo run build --force

--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.

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 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

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

This is useful when using --scope in CI as it guarantees that every dependency needed for the execution scope 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.

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

--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:

{
"turbo": {
"pipeline": {
"build": {
"dependsOn": [
"^build"
]
},
"test": {
"dependsOn": [
"^build"
]
}
}
}
}
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.

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

--scope

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.)

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 instead.

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

turbo run build --serial

--since

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

turbo run build --since=origin/main

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.

--token

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

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.

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.

--trace

type: string

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

Important: The trace viewer doesn't work under Windows Subsystem for Linux.

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 and use the left heavy or sandwich view modes.

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.

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.

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

-v, -vv, -vvv

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

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.

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.

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.jsons
  • 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.

Options

--url

type: string

Defaults to https://vercel.com.

--api

type: string

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

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 through 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