@williamcachamwri/markui-cli

Official MarkUI command-line interface powered by the Vite Node API.

Install

Install the CLI together with the MarkUI runtime and Vite integration:

npm install \
  @williamcachamwri/markui-cli \
  @williamcachamwri/markui-core \
  @williamcachamwri/markui-compiler \
  @williamcachamwri/markui-react \
  @williamcachamwri/markui-vite

Add scripts to the application package:

{
  "scripts": {
    "dev": "markui dev",
    "check": "markui check",
    "build": "markui build",
    "preview": "markui preview",
    "doctor": "markui doctor"
  }
}

The application still uses a normal vite.config.ts with the MarkUI plugin. The CLI calls Vite through its Node API rather than spawning another shell command.

Commands

markui dev

Starts the Vite development server after loading the project configuration.

markui dev
markui dev --host
markui dev --host 0.0.0.0 --port 3000 --open
markui dev --config vite.config.ts --clear-screen=false

Interactive shortcuts are enabled only in a TTY and are disabled in CI:

• h: show Vite help
• r: restart the server
• o: open the browser
• c: clear the terminal
• q: close the server

markui check

Validates every Markdown page discovered by the configured MarkUI Vite plugin without producing a bundle.

markui check
markui check --format json

Human output includes stable diagnostic codes, file names, source locations, code frames, and actionable hints. JSON output is intended for CI and editor integrations:

interface CheckOutput {
  valid: boolean
  filesChecked: number
  errorCount: number
  warningCount: number
  diagnostics: Array<{
    code: string
    severity: 'error' | 'warning'
    message: string
    file: string
    line: number
    column: number
    endLine?: number
    endColumn?: number
    hint?: string
  }>
}

The command exits with code 0 when every page is valid and code 1 when an error diagnostic exists.

markui doctor

Inspects whether a project is wired correctly before debugging Vite or Markdown behavior:

markui doctor
markui doctor --format json

Checks include:

• supported Node and Vite versions;
• aligned MarkUI package versions;
• a markUI() plugin in the Vite config;
• an existing page directory;
• packaged @williamcachamwri/markui-vite/client typings;
• imported MarkUI styles;
• project-wide Markdown diagnostics.

Human output is intended for local troubleshooting. JSON output is stable enough for CI and support tooling. The command exits nonzero when an error-level health check fails.

markui build

Runs the same project-wide Markdown validation used by markui check, then calls Vite's production build API. Invalid Markdown stops before bundle generation.

markui build
markui build --config vite.config.ts --clear-screen=false

markui preview

Starts Vite's production preview server:

markui preview
markui preview --host 127.0.0.1 --port 4173 --open

Directive failures

The compiler rejects malformed directives before Vite generates JavaScript. Examples include:

:::card
Missing close

# Extra close

:::

:::grid
:::card
Equal-width nested fences are ambiguous
:::
:::

Use a longer fence for each outer nesting level:

::::grid
:::card
Valid nested content
:::
::::

Markers inside inline code and fenced code blocks remain literal documentation content.

Environment

• Node.js ^20.19.0 || >=22.12.0
• Vite ^7.0.0 || ^8.0.0
• macOS, Linux, and Windows

Set NO_COLOR=1 to disable ANSI styling. Set MARKUI_DEBUG=1 to include internal stack traces for startup failures.

Cross-platform release verification

The packed CLI is installed into a clean application and exercised on Linux, macOS, and Windows in CI. The smoke test verifies the generated markui/markui.cmd binary, --version, strict checks, client declarations, virtual routes, sidecar logic, and a Vite production build.