@docvia/cli

@docvia/cli is the command-line entry point for docvia. It ships the docvia binary, loads your docvia.config.ts, and drives @docvia/compiler's compile() routine. Beyond the four commands, it re-exports defineConfig so config files can import everything they need from a single package.

Install

pnpm add -D @docvia/cli

Once installed, the docvia binary is available through your package runner:

pnpm exec docvia --help

A typical package.json wires the commands into scripts:

{
  "scripts": {
    "docs:dev": "docvia dev",
    "docs:build": "docvia build",
    "docs:preview": "docvia preview"
  }
}

Package exports

exports

bin

Programmatic API

The package's . entry is importable in addition to being runnable as a binary.

runCli

function runCli(argv?: readonly string[]): Promise<void>;

The programmatic entry point. It builds the underlying commander program and invokes parseAsync. The promise resolves once the parsed command finishes and rejects on parser errors. argv defaults to process.argv, so passing nothing replicates a direct shell invocation.

import { runCli } from "@docvia/cli";

// Equivalent to running `docvia build --no-cache`
await runCli(["node", "docvia", "build", "--no-cache"]);

The bin.mjs shim calls runCli() explicitly; any downstream tooling that wants to run docvia in-process can do the same.

defineConfig

import { defineConfig } from "@docvia/cli";

Re-exported from @docvia/plugins. It is the identity helper used in docvia.config.ts to get full type-checking and editor completion on the config object.

// docvia.config.ts
import { defineConfig } from "@docvia/cli";

export default defineConfig({
  sourceDir: "docs",
  outDir: ".docvia",
});

Re-exported types

Global options

docvia --version

Prints the installed CLI version. The version is read from process.env.npm_package_version and falls back to 0.1.0 when that variable is absent.

Commands

The CLI exposes four commands: init, build, dev, and preview.

docvia init

Scaffolds a new docvia project: a docs/ directory with three starter Markdown files plus a docvia.config.ts at the project root.

When --renderer is omitted, the renderer is autodetected from package.json dependencies:

• svelte or @sveltejs/kit present → svelte
• react or next present → react
• otherwise → none

Files created:

• docs/index.md
• docs/getting-started.md
• docs/components.md
• docvia.config.ts

After scaffolding, init prints install hints for the packages that match the chosen renderer.

# Scaffold into the current directory, autodetecting the renderer
docvia init

# Scaffold a Svelte project into ./website, overwriting any existing config
docvia init --dir ./website --renderer svelte --force

docvia build

Compiles documentation once. It loads the config, validates the environment, and calls compile().

build throws a docviaError with code CONFIG_ERROR when the docs directory is missing or no renderer is configured. It passes incremental: !noCache to compile(), so omitting --no-cache keeps the incremental cache, and passing it forces a clean build.

On success it prints the build duration along with file and page counts.

# Standard build
docvia build

# Full rebuild with overridden paths
docvia build --docs content --out dist/docs --no-cache

docvia dev

Runs an initial compile, then watches for changes and rebuilds incrementally.

Behavior:

• After the initial compile, chokidar watches the source directory and the config file.
• The watcher uses awaitWriteFinish with a stabilityThreshold of 50 ms and a pollInterval of 10 ms, plus a 20 ms debounce, so rapid saves coalesce into a single rebuild.
• A build lock serializes rebuilds, so overlapping change events never run two compilations at once.
• When the config file changes, the config is reloaded before the next rebuild.
• SIGINT and SIGTERM trigger a graceful shutdown of the watcher.

docvia dev --docs content

docvia preview

Serves the already-compiled .docvia/ output over a local HTTP server using sirv.

The command validates that the port is within the valid range before binding via node:http.

preview is a sanity check for the compiled artifacts, not a runtime. Render the compiled output inside your framework app (Vite, Next.js, SvelteKit) for the real integration.

docvia preview --out .docvia --port 5000

End-to-end example

# 1. Scaffold
docvia init --renderer react

# 2. Iterate
docvia dev

# 3. Ship
docvia build
docvia preview