---
description: Run Doctrine's Vite development server and static production build.
---

# CLI reference

The `doctrine` binary exposes two commands. It treats the current working directory as the project
root, loads `doctrine.config.*` from there, and resolves a relative content directory from that root.

```sh
doctrine dev [directory] [--host localhost] [--port 5173]
doctrine build [directory] [--site-url https://example.com/docs/] [--out-dir dist]
```

`[directory]` defaults to `docs` and must exist.

## `doctrine dev`

Starts a custom Vite server with SSR, client hydration, file watching, and an in-memory development
search index.

| Argument or option | Default     | Meaning                                                |
| ------------------ | ----------- | ------------------------------------------------------ |
| `[directory]`      | `docs`      | MDX content directory, relative to the project root.   |
| `--host`           | `localhost` | Interface passed to Vite.                              |
| `--port`           | `5173`      | Integer port from `0` through `65535`; `0` is dynamic. |

```sh
doctrine dev
doctrine dev website --host 0.0.0.0 --port 4173
```

The command keeps running until the server is stopped. MDX and navigation changes update the site;
when page actions are enabled, matching `.md` source routes update with the authored files. The
Pagefind development data is rebuilt lazily after the next search request.

## `doctrine build`

Builds the client and SSR bundles, prerenders every navigation route, writes `404.html` and the
enabled `.md` source routes, and creates the Pagefind index.

| Argument or option | Default                       | Meaning                                                     |
| ------------------ | ----------------------------- | ----------------------------------------------------------- |
| `[directory]`      | `docs`                        | MDX content directory, relative to the project root.        |
| `--site-url`       | config or `http://localhost/` | Final HTTP(S) URL, including any deployment pathname.       |
| `--out-dir`        | config or `dist`              | Output path resolved from the root unless already absolute. |

```sh
doctrine build
doctrine build website \
  --site-url https://user.github.io/project/ \
  --out-dir build
```

CLI values override `siteUrl` and `outDir` from the root config for that invocation. The output must
remain inside the project root, cannot equal the root, and cannot be inside the MDX directory. The
client build empties it before writing.

On success, Doctrine prints the number of document routes and the resolved output path. The route
count does not include the shared 404 page.

## Help and failures

```sh
doctrine --help
```

The CLI exits non-zero for unknown commands or options, repeated positional directories, missing
option values, invalid ports, missing input directories, invalid config/navigation, unsafe output,
compilation failures, or search-index failures. Errors are printed as messages without a custom error
code contract.