turbo run

Purpose and Scope

turbo run is the primary command for executing repository tasks through Turborepo. A task is a package script, such as build, lint, test, or dev, that is registered in turbo.json so Turborepo can schedule it across the workspace. Instead of manually running each package script in sequence, you describe relationships between tasks once and then ask turbo run to execute the requested work as a dependency-aware task graph. In everyday use, this command is the bridge between your package manager scripts and Turborepo’s parallel execution, caching, filtering, and CI workflows.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx, apps/docs/content/docs/crafting-your-repository/understanding-your-repository.mdx

This reference focuses on behavior documented in the repository-crafting guides: how tasks are discovered, how multiple task names are handled, how task dependencies affect order, how cacheable outputs are restored, how filters narrow work, and how long-running development tasks are configured. The guide evidence also shows turbo run as an incremental adoption mechanism: you do not need to move every script in every package at once. You can begin with one task in a few packages, add configuration as you understand the graph, and use the same command shape locally and in CI.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

Relevant Source Files

• apps/docs/content/docs/crafting-your-repository/understanding-your-repository.mdx - Shows how calling turbo run with no task arguments lists potential tasks and the packages where they are defined.
• apps/docs/content/docs/crafting-your-repository/caching.mdx - Explains the cache behavior users observe when running tasks, including first-run misses, later hits, local cache storage, and Remote Cache setup.
• apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx - Defines the task model used by turbo run: tasks, package scripts, dependsOn, outputs, and parallel execution.
• apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx - Describes running turbo in CI, Remote Cache environment variables, --filter, and --affected usage in pipelines.
• apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx - Grounds package graph behavior by showing how internal packages are discovered through package.json and linked through workspace dependencies.
• apps/docs/content/docs/crafting-your-repository/developing-applications.mdx - Documents long-lived development tasks, cache: false, persistent: true, dependsOn, terminal UI behavior, and turbo dev --filter=web.

Command Shape and Task Discovery

The command shape is turbo run <task...>, and first-party docs also show the shorter form turbo <task> for common task execution examples such as turbo build and turbo dev. When no task names are supplied, turbo run becomes an inspection command rather than an executor: it prints a list of potential tasks and the packages in which those tasks are defined. That behavior is useful before writing CI scripts or onboarding to a new monorepo because it tells you which task names are actually present across package package.json files.

Sources: apps/docs/content/docs/crafting-your-repository/understanding-your-repository.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/crafting-your-repository/developing-applications.mdx

turbo run
turbo run build
turbo run lint build test
turbo build
turbo dev

Task discovery starts with the root turbo.json. Each key in the tasks object names a task that can be executed by turbo run; Turborepo then searches packages for scripts in their package.json with the same name. If build is configured in turbo.json, packages that declare a build script become candidates for turbo run build. The repository guides emphasize that a task definition with no dependencies and no outputs is technically runnable but usually incomplete for real builds, because execution order and cached files have not yet been described.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

Execution Model and Dependency Ordering

turbo run builds a task graph from two kinds of relationships: package relationships and task relationships. Package relationships come from workspace package manifests; internal packages are named in package.json, imported by that name, and connected through workspace dependencies. Task relationships come from turbo.json, especially dependsOn. The result is a graph where Turborepo can run independent work in parallel while still respecting the order you need. The docs contrast sequential workspace commands like lint && build && test with turbo run lint build test, where Turborepo parallelizes every safe portion of the workload.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx, apps/docs/content/docs/crafting-your-repository/creating-an-internal-package.mdx

A common dependency rule is "dependsOn": ["^build"]. The caret microsyntax means the same task should run in direct dependencies before it runs in the target package. This is the usual shape for application builds that consume compiled internal packages: build libraries first, then build the app that depends on them. The important operational point is that you do not encode that ordering in the shell command. You still run turbo run build; the order is inferred from the package graph and the task configuration.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

Root tasks and explicit package tasks extend the same model. The development guide shows a root setup task named //#dev:setup that can run before dev. That notation matters for turbo run users because it lets repository-level preparation participate in the graph beside package-local scripts. In the example, dev depends on //#dev:setup, and the setup task declares .codegen/** as an output. This is how you keep preparatory work reproducible without hiding it inside a long shell script that Turborepo cannot reason about.

Sources: apps/docs/content/docs/crafting-your-repository/developing-applications.mdx

Caching, Outputs, and Remote Cache

Caching is central to what users experience when they run tasks through Turborepo. The caching guide defines the core promise as avoiding repeated work: when a task is cacheable, Turborepo uses a fingerprint of known inputs to find prior results and restore outputs. A first run with a new input set is a cache miss, because the local filesystem cache and Remote Cache do not yet contain the result. A later run with the same inputs can be restored from cache instead of rebuilding from zero, saving time on developer machines and in CI.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx

Outputs are the files Turborepo is allowed to cache and restore for a task. The configuring guide warns that defining build as an empty task will run package scripts but will not cache file outputs, which quickly leads to incorrect expectations. In practice, a cacheable task should declare output globs such as dist/**, framework build directories, or generated artifacts that are safe to restore. Turborepo assumes tasks are deterministic: if a task can produce different outputs from the same known inputs, cache hits may not reflect what you expect.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx

turbo run build
turbo run build

The same command participates in local and Remote Caching. Locally, task results are stored in .turbo/cache. To share artifacts with teammates and CI, the caching guide shows authenticating with npx turbo login and linking the repository with npx turbo link; after that, task runs can send outputs to the Remote Cache. In CI, the documented environment variables are TURBO_TOKEN, the bearer token used to access Remote Cache, and TURBO_TEAM, the account name associated with the repository when using Vercel Remote Cache.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

Filtering, Affected Work, and CI Usage

--filter narrows the package graph before tasks are executed. The docs show filters working with turbo ls and state that filters apply to run in the same way. In development, turbo dev --filter=web runs the dev task for a specific application and the relevant part of its graph. In CI, filters can target packages, directories, and Git history. That makes --filter the main tool for converting a broad task definition into focused work for a pull request, deploy job, or package-specific workflow.

Sources: apps/docs/content/docs/crafting-your-repository/understanding-your-repository.mdx, apps/docs/content/docs/crafting-your-repository/developing-applications.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx

turbo run build --filter=web
turbo dev --filter=web
turbo ls --filter ...ui

The CI guide also calls out --affected as a way to run tasks only in packages that have changes. That workflow depends on source control history being available on the CI machine; shallow clones may not contain enough history for Git-based filtering. When debugging why affected work is larger than expected, the docs recommend turbo query to inspect invalidation reasons such as file changes or dependency changes. The practical sequence is to configure tasks once, use Remote Cache credentials in CI, then add --filter or --affected when a job should execute less than the whole repository.

Sources: apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx, apps/docs/content/docs/crafting-your-repository/understanding-your-repository.mdx

Development Tasks and Output Controls

Long-running tasks need different configuration from build tasks. The development guide defines a dev task with "cache": false and "persistent": true. cache: false tells Turborepo not to cache results, which is appropriate for development servers, watch processes, and interactive scripts that respond to continuous changes. persistent: true tells Turborepo that the task is expected to keep running until stopped. It also prevents accidental task dependencies on work that will not exit, making the graph safer to reason about.

Sources: apps/docs/content/docs/crafting-your-repository/developing-applications.mdx

{
  "tasks": {
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

For local development, the command output is not just a stream of logs. The docs describe Turborepo’s terminal UI as an interactive experience around tasks, with keybinds for showing a keybind popup, selecting tasks, pinning a task, hiding the task list, and copying highlighted logs. These controls matter most when turbo run starts several application or package processes at the same time. Instead of opening many terminals, developers can run the graph once and navigate the output from a single interface.

Sources: apps/docs/content/docs/crafting-your-repository/developing-applications.mdx

Compact Reference

Use turbo run after the repository has a task model, not as a replacement for that model. First, define tasks in turbo.json; then add ordering with dependsOn; then add outputs for cacheable tasks; then distinguish persistent development tasks from finite build, lint, or test tasks. Once that foundation is in place, the same command can serve local development, CI pipelines, and repository inspection. For next steps, read the configuration reference for the full task schema, the caching page for hash inputs and outputs, and the query command reference when you need to explain why a package was selected.

Sources: apps/docs/content/docs/crafting-your-repository/configuring-tasks.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/crafting-your-repository/constructing-ci.mdx