0
# Command-Line Interface
1

2
VitePress provides a comprehensive CLI for project initialization, development server management, building for production, and preview serving. The CLI supports extensive configuration options and can be used both directly and programmatically.
3

4
## Capabilities
5

6
### Development Commands
7

8
Commands for running development servers and working with VitePress projects during development.
9

10
#### dev
11

12
Start the VitePress development server with hot module replacement and fast rebuilds.
13

14
```bash { .api }
15
# Start development server
16
vitepress [dev] [root]
17

18
# Command variants
19
vitepress dev
20
vitepress dev ./docs
21
vitepress dev --port 3000
22
vitepress dev --host 0.0.0.0 --port 8080
23
```
24

25
**Options:**
26

27
```bash { .api }
28
--port <port>        # Server port (default: 5173)
29
--host <host>        # Server host (default: localhost)  
30
--https              # Enable HTTPS with self-signed certificates
31
--open [path]        # Open browser on server start
32
--base <path>        # Override base URL for development
33
--force              # Force dependency optimization
34
--cors               # Enable CORS
35
--strictPort         # Exit if port is already in use
36
--clearScreen        # Clear screen on restart (default: true)
37
```
38

39
**Usage Examples:**
40

41
```bash
42
# Basic development server
43
vitepress dev
44

45
# Custom port and host
46
vitepress dev --port 3000 --host 0.0.0.0
47

48
# HTTPS development server  
49
vitepress dev --https --port 443
50

51
# Development with custom base path
52
vitepress dev --base /my-docs/
53

54
# Force optimization and open browser
55
vitepress dev --force --open
56

57
# Development for specific directory
58
vitepress dev ./my-docs --port 8080
59
```
60

61
### Build Commands
62

63
Commands for building VitePress sites for production deployment.
64

65
#### build
66

67
Build VitePress site for production with static site generation and optimization.
68

69
```bash { .api }
70
# Build for production
71
vitepress build [root]
72

73
# Command variants  
74
vitepress build
75
vitepress build ./docs
76
vitepress build --outDir ./dist
77
vitepress build --base /my-site/
78
```
79

80
**Options:**
81

82
```bash { .api }
83
--outDir <dir>       # Output directory (default: .vitepress/dist)
84
--base <path>        # Override base URL for build
85
--target <target>    # Build target (default: 'modules')
86
--minify [minifier]  # Enable/disable minification (default: 'esbuild')
87
--sourcemap          # Generate source maps
88
--ssr                # Enable server-side rendering
89
--mpa                # Build in Multi-Page Application mode
90
--emptyOutDir        # Empty output directory before build (default: true)
91
```
92

93
**Usage Examples:**
94

95
```bash
96
# Basic production build
97
vitepress build
98

99
# Build with custom output directory
100
vitepress build --outDir ./public
101

102
# Build with custom base path
103
vitepress build --base /docs/
104

105
# MPA mode build
106
vitepress build --mpa
107

108
# Build with source maps and no minification
109
vitepress build --sourcemap --minify false
110

111
# Build specific directory
112
vitepress build ./my-docs --outDir ./build
113
```
114

115
### Preview Commands
116

117
Commands for serving and previewing built VitePress sites.
118

119
#### preview / serve
120

121
Serve a built VitePress site for testing and preview purposes.
122

123
```bash { .api }
124
# Preview built site
125
vitepress preview [root]
126
vitepress serve [root]
127

128
# Command variants
129
vitepress preview
130
vitepress serve ./docs
131
vitepress preview --port 4000
132
```
133

134
**Options:**
135

136
```bash { .api }
137
--port <port>        # Server port (default: 4173)
138
--host <host>        # Server host (default: localhost)
139
--https              # Enable HTTPS
140
--open [path]        # Open browser on server start
141
--base <path>        # Override base URL for preview
142
--outDir <dir>       # Directory to serve (default: .vitepress/dist)
143
--strictPort         # Exit if port is already in use
144
--cors               # Enable CORS
145
```
146

147
**Usage Examples:**
148

149
```bash
150
# Basic preview server
151
vitepress preview
152

153
# Preview on custom port
154
vitepress preview --port 8080
155

156
# Preview with custom base path
157
vitepress preview --base /my-docs/
158

159
# HTTPS preview server
160
vitepress preview --https --port 443
161

162
# Preview and open browser
163
vitepress preview --open
164

165
# Serve from custom directory
166
vitepress preview --outDir ./build
167
```
168

169
### Project Initialization
170

171
Commands for creating new VitePress projects and scaffolding.
172

173
#### init
174

175
Initialize a new VitePress project with interactive setup.
176

177
```bash { .api }
178
# Initialize new project
179
vitepress init [root]
180

181
# Command variants
182
vitepress init
183
vitepress init ./my-docs
184
vitepress init --theme default
185
```
186

187
**Interactive Options:**
188

189
The `init` command provides an interactive setup wizard that asks for:
190

191
- Project directory
192
- Site title and description  
193
- Theme selection (default, custom, or extend existing)
194
- TypeScript support
195
- Git repository initialization
196
- Package manager choice (npm, yarn, pnpm)
197

198
**Usage Examples:**
199

200
```bash
201
# Interactive initialization
202
vitepress init
203

204
# Initialize in specific directory
205
vitepress init ./documentation
206

207
# Non-interactive with defaults
208
echo -e "y\nMy Docs\nDocumentation site\ndefault\nn\ny\nnpm" | vitepress init
209
```
210

211
### Programmatic API
212

213
Functions for using VitePress CLI functionality programmatically in Node.js applications.
214

215
#### init
216

217
Programmatic project initialization function.
218

219
```typescript { .api }
220
/**
221
 * Interactive project initialization
222
 * @param root - Target directory for initialization (optional)
223
 * @returns Promise that resolves when initialization is complete
224
 */
225
function init(root?: string): Promise<void>;
226
```
227

228
**Usage Examples:**
229

230
```typescript
231
import { init } from "vitepress";
232

233
// Interactive initialization
234
await init();
235

236
// Initialize in specific directory
237
await init("./my-documentation");
238

239
// Use in custom setup scripts
240
async function setupProject(projectName: string) {
241
  const projectDir = `./${projectName}`;
242
  
243
  // Create directory
244
  await fs.mkdir(projectDir, { recursive: true });
245
  
246
  // Initialize VitePress
247
  await init(projectDir);
248
  
249
  console.log(`VitePress project created in ${projectDir}`);
250
}
251
```
252

253
#### scaffold
254

255
Programmatic project scaffolding with configuration options.
256

257
```typescript { .api }
258
/**
259
 * Scaffold VitePress project files programmatically
260
 * @param options - Scaffolding configuration options
261
 * @returns Path to created project
262
 */
263
function scaffold(options: ScaffoldOptions): string;
264

265
interface ScaffoldOptions {
266
  /**
267
   * Target directory for the project
268
   */
269
  root: string;
270
  
271
  /**
272
   * Site title
273
   */
274
  title?: string;
275
  
276
  /**
277
   * Site description
278
   */
279
  description?: string;
280
  
281
  /**
282
   * Theme type to use
283
   * @default 'default'
284
   */
285
  theme?: "default" | "custom" | "extend";
286
  
287
  /**
288
   * Enable TypeScript support
289
   * @default false
290
   */
291
  typescript?: boolean;
292
  
293
  /**
294
   * Initialize git repository
295
   * @default true
296
   */
297
  git?: boolean;
298
  
299
  /**
300
   * Package manager to use
301
   * @default 'npm'
302
   */
303
  packageManager?: "npm" | "yarn" | "pnpm";
304
  
305
  /**
306
   * Include sample content
307
   * @default true
308
   */
309
  sampleContent?: boolean;
310
  
311
  /**
312
   * Custom template directory
313
   */
314
  template?: string;
315
}
316
```
317

318
**Usage Examples:**
319

320
```typescript
321
import { scaffold } from "vitepress";
322

323
// Basic scaffolding
324
const projectPath = scaffold({
325
  root: "./my-docs",
326
  title: "My Documentation",
327
  description: "Comprehensive project documentation"
328
});
329

330
// Advanced scaffolding with TypeScript
331
const tsProjectPath = scaffold({
332
  root: "./ts-docs",
333
  title: "TypeScript Docs",
334
  description: "TypeScript project documentation",
335
  theme: "custom",
336
  typescript: true,
337
  packageManager: "pnpm",
338
  git: true,
339
  sampleContent: false
340
});
341

342
// Automated project creation
343
async function createDocsSite(config: ProjectConfig) {
344
  // Create the project
345
  const projectPath = scaffold({
346
    root: config.directory,
347
    title: config.title,
348
    description: config.description,
349
    typescript: config.useTypeScript,
350
    packageManager: config.packageManager
351
  });
352
  
353
  // Install dependencies
354
  execSync(`cd ${projectPath} && ${config.packageManager} install`);
355
  
356
  // Start development server
357
  execSync(`cd ${projectPath} && ${config.packageManager} run dev`);
358
}
359
```
360

361
### Environment Variables
362

363
Environment variables that affect VitePress CLI behavior.
364

365
#### Build Environment Variables
366

367
```bash { .api }
368
# Node environment
369
NODE_ENV=production          # Set production mode
370
NODE_ENV=development         # Set development mode
371

372
# VitePress specific
373
VITEPRESS_BASE=/my-docs/     # Override base URL
374
VITEPRESS_OUTDIR=./build     # Override output directory
375
VITEPRESS_PORT=3000          # Override default port
376
VITEPRESS_HOST=0.0.0.0       # Override default host
377

378
# Build optimization
379
VITEPRESS_CACHE_DIR=.cache   # Custom cache directory
380
VITEPRESS_TEMP_DIR=.temp     # Custom temp directory
381
VITEPRESS_PARALLEL=4         # Build parallelism level
382

383
# Debug options
384
DEBUG=vitepress:*            # Enable debug logging
385
VITEPRESS_DEBUG=true         # Enable VitePress debug mode
386
```
387

388
**Usage Examples:**
389

390
```bash
391
# Production build with custom base
392
VITEPRESS_BASE=/docs/ vitepress build
393

394
# Development with custom port
395
VITEPRESS_PORT=8080 vitepress dev
396

397
# Debug mode development
398
DEBUG=vitepress:* vitepress dev
399

400
# Parallel build
401
VITEPRESS_PARALLEL=8 vitepress build
402
```
403

404
### Configuration File Detection
405

406
VitePress CLI automatically detects and loads configuration files in the following order:
407

408
#### Configuration File Priority
409

410
```bash { .api }
411
# Configuration files (in priority order)
412
.vitepress/config.js         # JavaScript configuration
413
.vitepress/config.ts         # TypeScript configuration  
414
.vitepress/config.mjs        # ES modules JavaScript
415
.vitepress/config.mts        # ES modules TypeScript
416
vitepress.config.js          # Root JavaScript configuration
417
vitepress.config.ts          # Root TypeScript configuration
418
```
419

420
#### Config File Examples
421

422
```typescript
423
// .vitepress/config.ts
424
import { defineConfig } from "vitepress";
425

426
export default defineConfig({
427
  title: "My Site",
428
  description: "Site description",
429
  
430
  // CLI-specific overrides
431
  srcDir: "./src",
432
  outDir: "./build",
433
  cacheDir: "./.vitepress/cache",
434
  
435
  themeConfig: {
436
    nav: [
437
      { text: "Home", link: "/" },
438
      { text: "Guide", link: "/guide/" }
439
    ]
440
  }
441
});
442
```
443

444
### Advanced CLI Usage
445

446
Advanced patterns and workflows for VitePress CLI usage.
447

448
#### Scripting and Automation
449

450
```bash { .api }
451
#!/bin/bash
452
# deploy.sh - Automated deployment script
453

454
# Build the site
455
echo "Building VitePress site..."
456
vitepress build --base /my-docs/
457

458
# Deploy to server
459
echo "Deploying to production..."
460
rsync -avz .vitepress/dist/ user@server:/var/www/my-docs/
461

462
# Verify deployment
463
curl -f https://example.com/my-docs/ || exit 1
464

465
echo "Deployment successful!"
466
```
467

468
#### CI/CD Integration
469

470
```yaml
471
# .github/workflows/deploy.yml
472
name: Deploy VitePress Site
473

474
on:
475
  push:
476
    branches: [main]
477

478
jobs:
479
  deploy:
480
    runs-on: ubuntu-latest
481
    steps:
482
      - uses: actions/checkout@v3
483
      
484
      - name: Setup Node.js
485
        uses: actions/setup-node@v3
486
        with:
487
          node-version: '18'
488
          cache: 'npm'
489
      
490
      - name: Install dependencies
491
        run: npm ci
492
      
493
      - name: Build VitePress site
494
        run: vitepress build --base /docs/
495
        
496
      - name: Deploy to GitHub Pages
497
        uses: peaceiris/actions-gh-pages@v3
498
        with:
499
          github_token: ${{ secrets.GITHUB_TOKEN }}
500
          publish_dir: .vitepress/dist
501
```
502

503
#### Custom CLI Wrappers
504

505
```typescript
506
// scripts/dev.ts - Custom development script
507
import { createServer } from "vitepress";
508
import { spawn } from "child_process";
509

510
async function startDevelopment() {
511
  // Start VitePress dev server
512
  const server = await createServer(".", {
513
    port: 3000,
514
    host: "0.0.0.0"
515
  });
516
  
517
  await server.listen();
518
  console.log("VitePress dev server running at http://localhost:3000");
519
  
520
  // Start additional services
521
  const apiServer = spawn("node", ["api-server.js"], { stdio: "inherit" });
522
  const cssWatcher = spawn("sass", ["--watch", "styles:public/css"], { stdio: "inherit" });
523
  
524
  // Handle cleanup
525
  process.on("SIGINT", () => {
526
    server.close();
527
    apiServer.kill();
528
    cssWatcher.kill();
529
    process.exit();
530
  });
531
}
532

533
startDevelopment().catch(console.error);
534
```
535

536
### CLI Error Handling and Debugging
537

538
Common CLI issues and debugging techniques.
539

540
#### Debug Mode
541

542
```bash { .api }
543
# Enable debug logging
544
DEBUG=vitepress:* vitepress dev
545
DEBUG=vitepress:config vitepress build
546
DEBUG=vitepress:build vitepress build
547

548
# Verbose output
549
vitepress dev --debug
550
vitepress build --debug
551
```
552

553
#### Common Issues
554

555
```bash { .api }
556
# Port already in use
557
vitepress dev --port 3001
558

559
# Permission issues
560
sudo vitepress dev --port 80
561
# OR
562
vitepress dev --port 8080
563

564
# Memory issues
565
NODE_OPTIONS="--max-old-space-size=4096" vitepress build
566

567
# TypeScript errors
568
vitepress build --skipTs
569
```
570

571
#### Log Output Analysis
572

573
```typescript
574
// Custom logging in config
575
export default defineConfig({
576
  buildEnd: (config) => {
577
    console.log("Build completed!");
578
    console.log("Output directory:", config.outDir);
579
    console.log("Generated pages:", config.pages.length);
580
  },
581
  
582
  transformPageData: (pageData) => {
583
    console.log("Processing page:", pageData.relativePath);
584
    return pageData;
585
  }
586
});
587
```