1# turbo run
2 
3The primary command for executing tasks across your monorepo.
4 
5## Basic Usage
6 
7```bash
8# Full form (use in CI, package.json, scripts)
9turbo run <tasks>
10 
11# Shorthand (only for one-off terminal invocations)
12turbo <tasks>
13```
14 
15## When to Use `turbo run` vs `turbo`
16 
17**Always use `turbo run` when the command is written into code:**
18 
19- `package.json` scripts
20- CI/CD workflows (GitHub Actions, etc.)
21- Shell scripts
22- Documentation
23- Any static/committed configuration
24 
25**Only use `turbo` (shorthand) for:**
26 
27- One-off commands typed directly in terminal
28- Ad-hoc invocations by humans or agents
29 
30```json
31// package.json - ALWAYS use "turbo run"
32{
33  "scripts": {
34    "build": "turbo run build",
35    "dev": "turbo run dev",
36    "lint": "turbo run lint",
37    "test": "turbo run test"
38  }
39}
40```
41 
42```yaml
43# CI workflow - ALWAYS use "turbo run"
44- run: turbo run build --affected
45- run: turbo run test --affected
46```
47 
48```bash
49# Terminal one-off - shorthand OK
50turbo build --filter=web
51```
52 
53## Running Tasks
54 
55Tasks must be defined in `turbo.json` before running.
56 
57```bash
58# Single task
59turbo build
60 
61# Multiple tasks
62turbo run build lint test
63 
64# See available tasks (run without arguments)
65turbo run
66```
67 
68## Passing Arguments to Scripts
69 
70Use `--` to pass arguments through to the underlying package scripts:
71 
72```bash
73turbo run build -- --sourcemap
74turbo test -- --watch
75turbo lint -- --fix
76```
77 
78Everything after `--` goes directly to the task's script.
79 
80## Package Selection
81 
82By default, turbo runs tasks in all packages. Use `--filter` to narrow scope:
83 
84```bash
85turbo build --filter=web
86turbo test --filter=./apps/*
87```
88 
89See `filtering/` for complete filter syntax.
90 
91## Quick Reference
92 
93| Goal                | Command                    |
94| ------------------- | -------------------------- |
95| Build everything    | `turbo build`              |
96| Build one package   | `turbo build --filter=web` |
97| Multiple tasks      | `turbo build lint test`    |
98| Pass args to script | `turbo build -- --arg`     |
99| Preview run         | `turbo build --dry`        |
100| Force rebuild       | `turbo build --force`      |
101