title | description |
---|---|
CLI Reference |
Turborepo is a high-performance build system for JavaScript and TypeScript codebases. |
import Callout from "../../../../components/Callout"; import OuputModeTable from "../../../../components/output-mode-table.mdx";
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.
Options can be passed to turbo
in different ways. Options that require a value can be passed with an equals sign:
--opt=<value>
--opt="<value with a space>"
They can also be passed with a space between:
--opt value
--opt "value with a space"
Boolean options can be enabled as follows:
# To pass true
--opt
# To pass false
--opt=false
The following flags apply to all commands.
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.
turbo run build --color
Alternatively, you can also enable color using the FORCE_COLOR
environment variable (borrowed
from the supports-color nodejs package). Note that
this may also enable additional colored output from the actual tasks themselves if
they use supports-color
to determine whether or not to output with colored output.
declare -x FORCE_COLOR=1
turbo run build
Suppresses the use of color in the output when running turbo
in an interactive / TTY session.
turbo run build --no-color
Alternatively, you can also suppress color using the FORCE_COLOR
environment variable (borrowed
from the supports-color nodejs package).
declare -x FORCE_COLOR=0
turbo run build
Disables the update notification. This notification will be automatically disabled when running in CI environments, but can also be disabled manually via this flag.
turbo run build --no-update-notifier
Alternatively, you can also disable the update notification by using either the TURBO_NO_UPDATE_NOTIFIER
environment variable, or the NO_UPDATE_NOTIFIER
environment variable (borrowed from the update-notifier nodejs package).
declare -x TURBO_NO_UPDATE_NOTIFIER=1
turbo run build
Run npm scripts across all workspaces 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 configuration.
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"
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
flag is also passed.
turbo run build --concurrency=50%
turbo run test --concurrency=1
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
Set the working directory of the command.
turbo run build --cwd=./somewhere/else
Defaults to true
. Include dependent workspace consumers in the execution.
turbo run build --deps
turbo run build --no-deps
Example
Let's say you have workspaces 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.
Instead of executing tasks, display details about the affected workspaces 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 executedpackage
: The workspace in which to run the taskhash
: The hash of the task, used for cachingdirectory
: The directory where the task will be runcommand
: The actual command used to run the taskoutputs
: Location of outputs from the task that will cachedlogFile
: Location of the log file for the task rundependencies
: Tasks that must run before this taskdependents
: Tasks that must be run after this task
type: string
Controls the available environment variables to your tasks.
option | description |
---|---|
infer | infers strict mode or loose mode based on allowlist config |
loose | allows all environment variables |
strict | only allow declared variables |
PATH
, SHELL
, and SYSTEMROOT
are always available to all tasks.
In infer mode, Turborepo will look for experimentalPassThroughEnv
for
each task config, and experimentalGlobalPassThroughEnv
in the root of the
turbo.json
config. If either is defined, "strict" mode is inferred. If
neither is defined, then loose
mode is inferred.
In this mode, the value of experimentalGlobalPassThroughEnv
and the flag's
value ("infer") will only be incorporated into the global hash if
experimentalGlobalPassThroughEnv
is set.
In loose mode, all environment variables are made available to the task.
The value of experimentalGlobalPassThroughEnv
and the flag's value ("loose")
itself will be incorporated into the global hash.
In strict mode, only environment variables specified in the following keys are available to the task:
env
andexperimentalPassThroughEnv
in each task configurationglobalEnv
andexperimentalGlobalPassThroughEnv
in the root of your config
The value of experimentalGlobalPassThroughEnv
and the flag's value ("strict")
itself will be incorporated into the global hash.
If strict mode is specified or inferred, all tasks are run in strict mode, regardless of their configuration.
type: string[]
Specify combinations of workspaces, 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.
turbo run build --filter=my-pkg
turbo run test --filter=...^@scope/my-lib
turbo run build --filter=./apps/* --filter=!./apps/admin
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 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
.
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
turbo run build test lint --graph=my-graph.mermaid
Ignore existing cached artifacts and forcibly re-execute all tasks (overwriting artifacts that overlap)
turbo run build --force
The same behavior also be set via the TURBO_FORCE=true
environment variable.
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.
type: string[]
Ignore files or directories from impacting scope. Uses glob patterns under the hood.
turbo run build --ignore="apps/**/*"
turbo run build --ignore="packages/**/*"
turbo run build --ignore="packages/**/*" --ignore="\!/packages/not-this-one/**/*"
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.
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
Default false
. When true
, turbo
will add any workspaces that the workspaces 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.
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 --no-cache
Default false
. turbo
can run a standalone process in some cases to precalculate values used for determining what work needs to be done.
This standalone process (daemon) is an optimization, and not required for proper functioning of turbo
.
Passing --no-daemon
instructs turbo
to avoid using or creating the standalone process.
type: string
Set type of output logging. Defaults to "outputMode" for the task in turbo.json
.
Example
turbo run build --output-logs=full
turbo run build --output-logs=new-only
turbo run build --output-logs=errors-only
turbo run build --output-logs=none
Default false
. Restricts execution to include specified tasks only. This is very similar to how lerna
and pnpm
run tasks by default.
Given this pipeline in turbo.json
:
{
"$schema": "https://turbo.build/schema.json",
"pipeline": {
"build": {
"dependsOn": ["^build"]
},
"test": {
"dependsOn": ["^build"]
}
}
}
turbo run test --only
Will execute only the test
tasks in each workspace. It will not build
.
Default false
. Run commands in parallel across workspaces and ignore the task dependency graph.
turbo run lint --parallel --no-cache
turbo run dev --parallel --no-cache
Default false
. Ignore the local filesystem cache for all tasks. Only allow reading and caching artifacts using the remote cache.
turbo run build --remote-only
The same behavior can also be set via the TURBO_REMOTE_ONLY=true
environment variable.
type: string[]
Specify/filter workspaces 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 --scope="@example/a" --scope="@example/b" --no-cache --no-deps
Filter execution based on which workspaces have changed since a merge-base.
turbo run build --since=origin/main
Generates a JSON file in .turbo/runs
containing metadata about the run, including affected workspaces,
executed tasks (including their timings and hashes), expanded to the cache key based on your config
and all the files included in the cached artifact. This flag can be helpful to determine, among other
things:
- How turbo interpreted your glob syntax for
inputs
andoutputs
- What inputs changed between two task runs to produce a cache hit or miss
- How task timings changed over time
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 are using Remote Caching on Vercel and building your project on Vercel, this environment variable and flag are unnecessary because they are automatically set for you. Suppose you are 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.
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.
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.
turbo run build --preflight
The same behavior can also be set via the TURBO_PREFLIGHT=true
environment variable.
type: string
To view CPU trace, outputs the trace to the given file, use go tool trace [file]
.
turbo run build --trace="<trace-file-name>"
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>"
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>"
To specify log level, use --verbosity=<num>
or -v, -vv, -vvv
.
Info
:--verbosity=1
, or-v
Debug
:--verbosity=2
, or-vv
Trace
:--verbosity=3
, or-vvv
turbo run build -v
turbo run build --verbosity=2
turbo run build -vvv
Generate a sparse/partial monorepo with a pruned lockfile for a target workspace.
This command will generate folder called out
with the following inside of it:
- The full source code of all internal workspaces 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 workspaces in the pruned workspace.
- A copy of the root
package.json
. # Folder full source code for all workspaces 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
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'spackage.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
Connect machine to your Remote Cache provider. The default provider is Vercel.
type: string
Defaults to https://vercel.com/
.
type: string
Defaults to https://vercel.com/api
.
type: string
Connect to an sso-enabled Vercel team by providing your Team slug.
turbo login --sso-team=<team-slug>
Logs you out of your Vercel account.
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.
type: string
Defaults to https://api.vercel.com
Unlink the current directory from the Remote Cache.
Get the path to the turbo
binary.