---
name: vitepress-cli
description: Command-line interface for development, building, and previewing VitePress sites
---

# CLI Commands

VitePress provides four main commands: `dev`, `build`, `preview`, and `init`.

## Development Server

Start the dev server with hot module replacement:

```bash
# In current directory (dev command is optional)
vitepress

# Or explicitly
vitepress dev

# With project in subdirectory
vitepress dev docs
```

**Options:**

| Option          | Description                |
| --------------- | -------------------------- |
| `--open [path]` | Open browser on startup    |
| `--port <port>` | Specify port number        |
| `--base <path>` | Override base URL          |
| `--cors`        | Enable CORS                |
| `--strictPort`  | Exit if port is in use     |
| `--force`       | Ignore cache and re-bundle |

```bash
vitepress dev docs --port 3000 --open
```

## Production Build

Build static files for production:

```bash
vitepress build docs
```

**Options:**

| Option                    | Description                             |
| ------------------------- | --------------------------------------- |
| `--base <path>`           | Override base URL                       |
| `--target <target>`       | Transpile target (default: `modules`)   |
| `--outDir <dir>`          | Output directory (relative to cwd)      |
| `--assetsInlineLimit <n>` | Asset inline threshold in bytes         |
| `--mpa`                   | Build in MPA mode (no client hydration) |

```bash
vitepress build docs --outDir dist
```

## Preview Production Build

Locally preview the production build:

```bash
vitepress preview docs
```

**Options:**

| Option          | Description         |
| --------------- | ------------------- |
| `--port <port>` | Specify port number |
| `--base <path>` | Override base URL   |

```bash
vitepress preview docs --port 4173
```

## Initialize Project

Start the setup wizard:

```bash
vitepress init
```

This creates the basic file structure:

- `.vitepress/config.js` - Configuration
- `index.md` - Home page
- Optional example pages

## Package.json Scripts

Typical scripts configuration:

```json
{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}
```

## Key Points

- Dev server runs at `http://localhost:5173` by default
- Preview server runs at `http://localhost:4173`
- Production output goes to `.vitepress/dist` by default
- The `docs` argument specifies the project root directory
- Use `--base` to override base path without modifying config

<!--
Source references:
- https://vitepress.dev/reference/cli
-->
