1---
2name: vitest-cli
3description: Command line interface commands and options
4---
5 
6# Command Line Interface
7 
8## Commands
9 
10### `vitest`
11 
12Start Vitest in watch mode (dev) or run mode (CI):
13 
14```bash
15vitest                    # Watch mode in dev, run mode in CI
16vitest foobar             # Run tests containing "foobar" in path
17vitest basic/foo.test.ts:10  # Run specific test by file and line number
18```
19 
20### `vitest run`
21 
22Run tests once without watch mode:
23 
24```bash
25vitest run
26vitest run --coverage
27```
28 
29### `vitest watch`
30 
31Explicitly start watch mode:
32 
33```bash
34vitest watch
35```
36 
37### `vitest related`
38 
39Run tests that import specific files (useful with lint-staged):
40 
41```bash
42vitest related src/index.ts src/utils.ts --run
43```
44 
45### `vitest bench`
46 
47Run only benchmark tests:
48 
49```bash
50vitest bench
51```
52 
53### `vitest list`
54 
55List all matching tests without running them:
56 
57```bash
58vitest list                    # List test names
59vitest list --json             # Output as JSON
60vitest list --filesOnly        # List only test files
61```
62 
63### `vitest init`
64 
65Initialize project setup:
66 
67```bash
68vitest init browser            # Set up browser testing
69```
70 
71### `vitest --list-tags`
72 
73List tags defined in config without running tests:
74 
75```bash
76vitest --list-tags             # Human-readable list
77vitest --list-tags=json        # JSON output
78```
79 
80## Common Options
81 
82```bash
83# Configuration
84--config <path>           # Path to config file
85--project <name>          # Run specific project
86 
87# Filtering
88--testNamePattern, -t     # Run tests matching pattern
89--tagsFilter <expr>       # Run tests by tag expression, e.g. "db && !flaky"
90--changed                 # Run tests for changed files
91--changed HEAD~1          # Tests for last commit changes
92--dir <path>              # Limit test discovery to a directory
93 
94# Reporters
95--reporter <name>         # default, verbose, tree, dot, json, html, junit, minimal, blob
96--reporter=json --outputFile=report.json
97 
98# Coverage
99--coverage                # Enable coverage
100--coverage.provider v8    # Use v8 provider
101--coverage.reporter text,html
102 
103# Execution
104--shard <index>/<count>   # Split tests across machines
105--bail <n>                # Stop after n failures
106--retry <n>               # Retry failed tests n times
107--shuffle                 # Randomize test order
108--no-file-parallelism     # Run test files one at a time
109 
110# Watch mode
111--no-watch                # Disable watch mode
112--standalone              # Start without running (v4: runs matched files if a filter is passed)
113 
114# Environment
115--environment <env>       # jsdom, happy-dom, node
116--globals                 # Enable global APIs
117 
118# Debugging
119--inspect                 # Enable Node inspector
120--inspect-brk             # Break on start
121 
122# Output
123--silent                  # Suppress console output
124--no-color                # Disable colors
125```
126 
127## Package.json Scripts
128 
129```json
130{
131  "scripts": {
132    "test": "vitest",
133    "test:run": "vitest run",
134    "test:ui": "vitest --ui",
135    "coverage": "vitest run --coverage"
136  }
137}
138```
139 
140## Sharding for CI
141 
142Split tests across multiple machines. The blob reporter writes to `.vitest/blob/` by default:
143 
144```bash
145# Machine 1
146vitest run --shard=1/3 --reporter=blob --outputFile=reports/blob-1.json
147 
148# Machine 2
149vitest run --shard=2/3 --reporter=blob --outputFile=reports/blob-2.json
150 
151# Merge all blobs into a final report
152vitest --merge-reports=reports --reporter=junit --reporter=default
153```
154 
155## Watch Mode Keyboard Shortcuts
156 
157In watch mode, press:
158- `a` - Run all tests
159- `f` - Run only failed tests
160- `u` - Update snapshots
161- `p` - Filter by filename pattern
162- `t` - Filter by test name pattern
163- `q` - Quit
164 
165## Key Points
166 
167- Watch mode is default in dev, run mode in CI (when `process.env.CI` is set)
168- Use `--run` flag to ensure single run (important for lint-staged)
169- Both camelCase (`--testTimeout`) and kebab-case (`--test-timeout`) work
170- Boolean options can be negated with `--no-` prefix
171- Filter tests by tag with `--tagsFilter` (tags must be declared in config) — see [features-test-tags](features-test-tags.md)
172- `--merge-reports` and `--reporter=blob` do not work in watch mode
173 
174<!-- 
175Source references:
176- https://vitest.dev/guide/cli.html
177-->
178