references/core-cli.md

GitHub
namevitepress-cli
descriptionCommand-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:

# 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
vitepress dev docs --port 3000 --open

Production Build

Build static files for production:

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)
vitepress build docs --outDir dist

Preview Production Build

Locally preview the production build:

vitepress preview docs

Options:

Option Description
--port <port> Specify port number
--base <path> Override base URL
vitepress preview docs --port 4173

Initialize Project

Start the setup wizard:

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:

{
  "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