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## Common Options
72 
73```bash
74# Configuration
75--config <path>           # Path to config file
76--project <name>          # Run specific project
77 
78# Filtering
79--testNamePattern, -t     # Run tests matching pattern
80--changed                 # Run tests for changed files
81--changed HEAD~1          # Tests for last commit changes
82 
83# Reporters
84--reporter <name>         # default, verbose, dot, json, html
85--reporter=html --outputFile=report.html
86 
87# Coverage
88--coverage                # Enable coverage
89--coverage.provider v8    # Use v8 provider
90--coverage.reporter text,html
91 
92# Execution
93--shard <index>/<count>   # Split tests across machines
94--bail <n>                # Stop after n failures
95--retry <n>               # Retry failed tests n times
96--sequence.shuffle        # Randomize test order
97 
98# Watch mode
99--no-watch                # Disable watch mode
100--standalone              # Start without running tests
101 
102# Environment
103--environment <env>       # jsdom, happy-dom, node
104--globals                 # Enable global APIs
105 
106# Debugging
107--inspect                 # Enable Node inspector
108--inspect-brk             # Break on start
109 
110# Output
111--silent                  # Suppress console output
112--no-color                # Disable colors
113```
114 
115## Package.json Scripts
116 
117```json
118{
119  "scripts": {
120    "test": "vitest",
121    "test:run": "vitest run",
122    "test:ui": "vitest --ui",
123    "coverage": "vitest run --coverage"
124  }
125}
126```
127 
128## Sharding for CI
129 
130Split tests across multiple machines:
131 
132```bash
133# Machine 1
134vitest run --shard=1/3 --reporter=blob
135 
136# Machine 2
137vitest run --shard=2/3 --reporter=blob
138 
139# Machine 3
140vitest run --shard=3/3 --reporter=blob
141 
142# Merge reports
143vitest --merge-reports --reporter=junit
144```
145 
146## Watch Mode Keyboard Shortcuts
147 
148In watch mode, press:
149- `a` - Run all tests
150- `f` - Run only failed tests
151- `u` - Update snapshots
152- `p` - Filter by filename pattern
153- `t` - Filter by test name pattern
154- `q` - Quit
155 
156## Key Points
157 
158- Watch mode is default in dev, run mode in CI (when `process.env.CI` is set)
159- Use `--run` flag to ensure single run (important for lint-staged)
160- Both camelCase (`--testTimeout`) and kebab-case (`--test-timeout`) work
161- Boolean options can be negated with `--no-` prefix
162 
163<!-- 
164Source references:
165- https://vitest.dev/guide/cli.html
166-->
167