run
Run tasks specified in turbo.json
.
- [tasks]: Turborepo can run one or many tasks at the same time. To run a task through
turbo
, it must be specified inturbo.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.
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
and turbo
with global turbo
locally for ease
of use.
If no tasks are provided, turbo
will display what tasks are available for the packages in the repository.
Options
--affected
Automatically filter to only packages that are affected by changes on the current branch.
By default, the flag is equivalent to --filter=[main...HEAD]
. This considers changes between main
and HEAD
from Git's perspective.
You can override the default base and head with their respective System Environment Variables.
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.
--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 cacheremote
: Use the Remote Cache
When an a caching source is omitted, reading and writing are both disabled.
Cache sources use the following values:
rw
: Read and writer
: Read onlyw
: Write only- None (
local:
) : Does not use cache. Equivalent to omitting the cache source option.
--cache-dir <path>
Default: .turbo/cache
Specify the filesystem cache directory.
Ensure the directory is in your .gitignore
when changing it.
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
flag is also passed.
--continue
Default: false
Continue with task execution in the presence of an error (e.g. non-zero exit code from a task).
When --continue
is true
, turbo
will exit with the highest exit code value encountered during execution.
Good to know:
Specifying the --parallel
flag will automatically set
--continue
to true
unless explicitly set to false
.
--cwd <path>
Default: Directory of root turbo.json
Set the working directory of the command.
--dangerously-disable-package-manager-check
Turborepo uses your repository's lockfile to determine caching behavior, Package Graphs, and more. Because of this, we use the packageManager
field 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.
You may also opt out of this check using configuration in
turbo.json
or the
TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK
environment variable for broader coverage.
--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.
Good to know:
PATH
, SHELL
, and SYSTEMROOT
are always available to the task.
option | description |
---|---|
strict (Default) | Only allow explicitly listed environment variables to be available |
loose | Allow all environment variables to be available |
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:
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.
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.
--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] |
Good to know:
-F
is an alias for --filter
.Microsyntaxes for filtering
!
: Negate targets from the selection....
using packages: Select all packages in the 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.
Using a task identifier
You can also run a specific task for a specific package in the format of package-name#task-name
.
Good to know:
This will also run the task's dependencies. To run a task without its
dependencies, use the --only
flag.
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.
--force
Ignore existing cached artifacts and re-execute all tasks.
Good to know:
--force
will overwrite existing task caches.
The same behavior can also be set via the TURBO_FORCE
environment variable.
--framework-inference
Default: true
Specify whether or not to do Framework Inference for tasks.
When false
, automatic environment variable inclusion is disabled.
--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.
We recommend specifying file globs that you'd like to include your hashes in
the globalDependencies
key
in turbo.json
to make sure they are always accounted for.
--graph <file type>
Default: jpg
This command will generate an svg
, png
, jpg
, pdf
, json
, html
, or other supported output formats of the current task graph.
If Graphviz is not installed, or no filename is provided, this command prints the dot graph to stdout
.
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.
--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.
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.
Option | Description |
---|---|
prefix | Force prepending the prefix to logs |
none | No prefixes |
auto | turbo decides based on its own heuristics |
--no-cache
Deprecated
This flag is deprecated and will be removed in a future major release. Please
use the --cache
flag instead.
Default false
Do not cache results of the task.
--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
.
Passing --daemon
instructs 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
if it's defined in turbo.json
.
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
:
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.
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
instead.
--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.
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.
Profiles can be viewed in a tool like Perfetto.
--remote-cache-timeout
Default: 30
Set the timeout for Remote Cache operations in seconds.
--remote-only
Deprecated
This flag is deprecated and will be removed in a future major release. Please
use the --cache
flag instead.
Default: false
Ignore the local filesystem cache for all tasks, using Remote Cache for reading and caching task outputs.
--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
This flag can be helpful for debugging to determine things like:
- How
turbo
interpreted your glob syntax forinputs
andoutputs
- What inputs changed between two task runs to produce a cache miss
- How task timings changed over time
--token
A bearer token for Remote Caching. Useful for running in non-interactive shells in combination with the --team
flag.
This value can also be set using the TURBO_TOKEN
system variable. If both are present, the flag value will override the system variable.
Good to know:
If you are using Vercel Remote Cache and building your project on Vercel, you do not need to use this flag. This value will be automatically set for you.
--team
The slug of the Remote Cache team. Useful for running in non-interactive shells in combination with the --token
flag.
This value can also be set using the TURBO_TEAM
system variable. 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 |
Was this helpful?