CLI reference
Five commands are the whole surface. Global flags first, then each command with its usage, flags and an example.
Two flags work on every command: --config <path> points at a cairn.toml outside the working directory, and --quiet reduces output to errors only. cairn --version and cairn help <command> do what they say.
cairn init
Scaffolds a working site: content folder, default theme, and a cairn.toml pointed at both.
cairn init [directory] [flags]| Flag | Default | Description |
|---|---|---|
--bare | off | Skip the sample content; scaffold config and theme only. |
--force | off | Initialise into a non-empty directory. Existing files are never overwritten. |
cairn init docs --bare
➤ scaffolded docs/ (config, theme)cairn serve
Local server with live reload. Drafts are always included; nothing is written to disk.
cairn serve [flags]| Flag | Default | Description |
|---|---|---|
--port | 4131 | Port to listen on. |
--host | 127.0.0.1 | Bind address. Use 0.0.0.0 to preview from another device. |
--open | off | Open the browser once the server is up. |
cairn serve --port 8080 --open
➤ serving on http://127.0.0.1:8080 (live reload)cairn build
Builds the site into the output directory. Incremental: only pages affected by a change are rebuilt.
cairn build [flags]| Flag | Default | Description |
|---|---|---|
--drafts | off | Include draft pages, overriding the config for this run. |
--clean | off | Discard the incremental cache and rebuild everything. |
--base-url | from config | Override base_url, for preview deployments. |
cairn build --clean
➤ 42 pages in 118ms → dist/cairn deploy
Builds, then hands dist/ to the deploy command named in your config. It is a convenience wrapper so "ship it" is one word; CI pipelines usually call build and upload themselves.
cairn deploy [flags]| Flag | Default | Description |
|---|---|---|
--dry-run | off | Build and print what would be uploaded, then stop. |
--skip-check | off | Skip the pre-deploy link check. Not recommended. |
cairn check
Lints the site without writing output: broken internal links, pages missing front matter, and images without alt text. Exits non-zero on any finding, which is what makes it useful in CI.
cairn check [flags]| Flag | Default | Description |
|---|---|---|
--external | off | Also verify external links respond. Slower; network-dependent. |
--strict | off | Treat warnings (missing descriptions, empty alt text) as failures. |
cairn check --strict
➤ 42 pages, 0 errors, 0 warnings