CLI Commands

The Boltdocs CLI powers the entire workflow: start your dev server, build the static site, preview the production bundle, audit your plugins for security warnings, check the health of your documentation, and generate changelog pages.

You run it with npx boltdocs or — once added to your package.json scripts — with pnpm docs:dev, pnpm docs:build and friends:

{
  "scripts": {
    "docs:dev": "boltdocs dev",
    "docs:build": "boltdocs build",
    "docs:preview": "boltdocs preview",
    "docs:audit": "boltdocs audit",
    "docs:doctor": "boltdocs doctor"
  }
}

All commands accept an optional positional [root] argument pointing at a project directory. It defaults to process.cwd().

dev — development server

Starts a high-performance Vite development server with instant Hot Module Replacement (HMR) for MDX files, style edits, and hot config reloads.

• Usage: boltdocs dev [root] [options] — or simply boltdocs [root] [options]

Dev server options

build — production build

Compiles your documentation into fully static, highly optimized HTML and JavaScript assets using the React Static Site Generation (SSG) engine.

• Usage: boltdocs build [root]

The output is generated in dist/ (configurable with outDir in boltdocs.config.ts).

preview — test the production bundle

Serves the static bundle generated from dist/ so you can verify performance, redirects, SEO tags, and page rendering before deploying.

• Usage: boltdocs preview [root] [options]

Preview options

audit — plugin security scan

Performs a fast static analysis of the source code of every plugin configured in your project. It scans for potentially sensitive behaviors — child process and dynamic code calls, network access, file reads and writes, environment variable reads, and metadata signals like install scripts or missing licenses — before you build or publish.

The scan never executes plugin code: it only reads package.json and the source files in node_modules. (Loading your config does evaluate the config file itself, but no plugin hook, Vite plugin, or install script is ever run.)

• Usage: boltdocs audit [root]

Exit codes (CI contract)

The command is fail-closed: an unresolved or unscanned plugin is treated as untrusted and never counts as "passed". Use it as a gate before merging third-party plugins:

- run: pnpm docs:build
- run: pnpm docs:audit

If the audit returns 1, your CI job fails — exactly when you want a human to review a plugin before it ships.

doctor — diagnostics and integrity checks

Runs automated checks on your documentation directory to find broken links, malformed frontmatter, missing translations, and other structural issues.

# Run doctor in the current folder
npx boltdocs doctor

# Automatically fix repairable issues
npx boltdocs doctor --fix

# Check external URLs in addition to internal paths
npx boltdocs doctor --check-external

# Initialize a default doctor.json file
npx boltdocs doctor --init

# Check build performance against configured budgets
npx boltdocs doctor --budget

Doctor options

Configuring doctor.json

Create a doctor.json at the root of your project to customize checks, severities, and CI behavior. Run boltdocs doctor --init to generate it and then adjust:

{
  "$schema": "https://boltdocs.vercel.app/schemas/doctor-config.schema.json",
  "checks": {
    "metadata": {
      "enabled": true,
      "titleMin": 10,
      "titleMax": 60,
      "descriptionMin": 50,
      "required": ["title", "description"]
    },
    "links": {
      "internal": true,
      "external": false,
      "timeout": 10000,
      "concurrency": 10
    },
    "i18n": { "enabled": true },
    "performance": {
      "enabled": true,
      "budgets": {
        "maxJSBundleSize": "200kb",
        "maxCSSBundleSize": "30kb",
        "maxPageHTMLSize": "80kb",
        "maxImagesKB": 500,
        "maxBuildTime": 30000,
        "maxFontCount": 3
      }
    }
  },
  "fix": {
    "confirmChanges": false,
    "backupFiles": false,
    "backupPath": ".boltdocs/backups"
  },
  "reporting": {
    "format": "pretty",
    "outputFile": ".boltdocs/reports/doctor.json",
    "failOnError": false,
    "maxWarnings": -1
  },
  "severity": {
    "missingTranslation": "warning",
    "brokenLink": "high",
    "brokenAnchor": "warning",
    "malformedFrontmatter": "high",
    "invalidFrontmatter": "high",
    "budgetExceeded": "warning"
  }
}

checks

Metadata options: titleMin (10), titleMax (60), descriptionMin (50), required (["title", "description"]), optional ([]), validateDates (false).

Links options: internal (true), external (false), timeout (10000 ms), concurrency (10), ignore ([] — regex patterns or exact URLs to skip).

Performance budgets accept maxJSBundleSize, maxCSSBundleSize, maxPageHTMLSize (strings like "200kb"), plus maxImagesKB, maxBuildTime (ms), and maxFontCount.

fix

reporting

generate-changelog — changelog generator

Parses a unified CHANGELOG.md (Keep a Changelog, Standard Version, or Semantic Release formats) and breaks it down into individual per-version MDX pages formatted for the Boltdocs theme.

# Break CHANGELOG.md into pages under docs/changelog
npx boltdocs generate-changelog CHANGELOG.md

Changelog options

Output

Each version is grouped by update type (Features, Bug Fixes, Performance, Refactor, Documentation, Chore) and written as an incremental page:

docs/changelog/
├── 1.v2.0.0.md
├── 2.v1.1.0.md
└── 3.v1.0.0.md

To surface the generated pages in the navbar, link them from boltdocs.config.ts:

export default defineConfig({
  theme: {
    navbar: [
      { label: 'Documentation', href: '/docs' },
      { label: 'Changelog', href: '/changelog' },
    ],
  },
})

Jesús Alcalá

Last updated on October 18, 2026