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, and clay <command> --help lists the options of one command.

#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 5.1.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 5.1.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

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 5.1.0 · check
│
✖  Checking links, translations and settings
│  ▲ Broken link in guides/setup.md: "instal.md" points to a missing page (/guides/instal)
│
└  1 problem; "clay build --strict" fails on them too

#clay search

npx clay search page order

Searches the docs the way the site’s search does, typos included, and shows where each match is: the file and line its section starts at, and the lines in it that match. Open the file at that line and change it; it suits people and AI agents alike.

1. Navigation › Order
   docs/latest/organizing/navigation.md:16  /organizing/navigation#order
     16: ## Order
     21: 1. Entries with an `order` come first, from the lowest number up.
     22: 2. All other entries follow in alphabetical order of their file or folder name.

2. Page Details › Previous and next
   docs/latest/features/page-details.md:56  /features/page-details#previous-and-next
     58: The last element of each page links to the previous and the next page, in the order of the sidebar, …

It searches the latest docs in the default language; --lang and --docs-version pick another, and --limit how many sections it shows (10). Pages generated from an OpenAPI spec name the spec as their file. With --json, it prints {"ok": true, "results": [{"file", "line", "title", "heading", "url", "lines": [...]}]}.

#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