Commands

Clay is used through one command, clay (or its alias clay-doc), with a subcommand:

clay <command> [options]

Run it with npx clay … in a project that has Clay installed, or through scripts in package.json. Every option of every command is in the CLI reference.

#clay dev

npx clay dev

Starts a development server at http://localhost:3000. It renders each page when you open it and reloads the browser whenever you change a page, an image or clay.yaml. Use it while writing; it is not meant to be put online.

While it runs, the terminal shows the address, warnings such as broken links, and each page it reloads:

┌  Clay 4.0.0 · dev
│
●  Loaded 40 pages from docs  languages de (30/30 translated) · 52ms
│
●  Started dev server  1.1s
│  ➜ Local:   http://localhost:3000/
│  ➜ Network: use --host to expose
│
│  ↻ Reloaded docs/writing/pages.md  10:24:31

--verbose shows the full output of Nuxt instead.

#clay build

npx clay build

Checks the docs, renders every page to HTML and writes the finished site to publish/public. While it runs, Clay shows its progress:

┌  Clay 4.0.0
│
●  Loaded 29 pages from docs  languages de (29/29 translated) · 310ms
│
●  Built client  199 modules · 960ms
│
●  Built server  126 modules · 420ms
│
◝  Prerendering pages · 41 routes

Without a terminal, for example in CI, it prints the finished steps as plain lines.

The build contains:

See SEO for the sitemap and robots.txt, and AI & agents for llms.txt and the Markdown of each page.

The build checks explain the warnings and --strict.

#clay preview

npx clay preview

Serves the last build at http://localhost:4173, behaving like GitHub Pages and most static hosts:

• the site is served under its baseURL,
• /guides/setup redirects to /guides/setup/,
• unknown addresses get the 404.html page with status 404.

Run it before you deploy: a page that works in clay preview works on the host. The terminal lists each address that got a 404, which points to a missing file or a wrong baseURL.

#clay edit

npx clay edit

Opens an editor in the terminal to create, edit, order, rename, move, delete and translate pages and folders, in every version and language, and to edit the settings in clay.yaml. See clay edit.

With a command, it makes one change and exits, for scripts and AI agents:

npx clay edit set guides/setup.md title="Setting up" order=2
npx clay edit help    # every command, with examples

See from scripts and AI agents.

#clay check New in Clay 4

npx clay check

Runs the build checks, broken links, settings, translations and versions, without building the site. It takes a second and exits with 1 when it finds a problem, so it suits a quick look after a change, pre-commit hooks and agents. With --json, it prints {"ok": …, "pages": …, "problems": [...]}.

#clay version

npx clay version 2.x

Copies docs/latest/ to docs/2.x/, keeping the latest docs as an older version. While the pages are right in docs/, it first moves them into docs/latest/: it shows what changes and asks before it does. In clay edit, V does the same. See versions.

#Options

Examples:

# Docs in a subfolder of a larger repository
npx clay build --root documentation

# Build into dist/public
npx clay build --out dist

# Preview on another port, reachable from other devices
npx clay preview --port 8080 --host