CLI

Run the installed binary through project scripts, pnpm exec oxiquill, npx oxiquill, or pnpm dlx oxiquill for project creation.

Global Options

Option	Behavior
--help, -h	Show global or command-specific usage and exit successfully.
--version	Print the installed Oxiquill package version.
--debug	Include cause and stack details in errors; expected errors are concise otherwise.
--config <path>	Use the selected Astro/Oxiquill config for every project command.
--	Forward all remaining supported arguments to the underlying Astro command.

Unknown options, missing option values, unknown commands, and extra positional arguments print usage and exit non-zero without modifying the project.

Commands

Command	Behavior
init [directory]	Create the versioned static starter. The current directory is the default.
dev	Generate required runtimes, then run the watcher and Astro development server.
dev:runtime	Run only the runtime/source watcher.
dev:astro	Run only Astro’s development server.
build	Generate required runtimes, run checks, and create the static site.
preview	Preview the existing production build.
check	Generate required runtimes, synchronize Astro types, and run Astro diagnostics.
docgen	Synchronize the manifest; --wasm dev | build also builds required runtimes.
clean	Remove only resolved Oxiquill-owned/generated and configured Astro output paths; preserve the verified download cache.
test-rust	Test optional helper crates.
test-rust-coverage	Test helper crates with the configured 85% coverage thresholds.
lint-rust	Run Clippy for all helper-crate targets with warnings denied.
doc-rust	Build helper-crate documentation without dependencies.
test-wasm	Generate runtimes and execute every generated Rust/Haskell cell with defaults.

dev:runtime performs one initial runtime synchronization before waiting for source changes. Use oxiquill dev:runtime --skip-initial when the runtime has already been generated: it registers the watcher without synchronizing at startup and waits for the first relevant docs or crate event. The combined dev command performs its explicit startup generation once and uses this mode internally.

dev, dev:astro, build, preview, and check accept their documented Astro arguments, including values after --. For example:

pnpm dev -- --host 0.0.0.0 --port 4321
pnpm check -- --minimumSeverity warning

Safe Project Creation

pnpm dlx oxiquill init my-docs
cd my-docs
pnpm install
pnpm check
pnpm build
pnpm preview

init accepts only a nonexistent target or an existing empty directory. It never overwrites a non-empty target, installs dependencies, initializes Git, or offers a force option. The generated npm package name is lowercase and safe; invalid or empty basenames fall back to oxiquill-docs. A failed creation removes partial output where practical and prints exact recovery or next steps.

Runtime and Tool Failures

Strict commands fail when a required compiler, generated artifact, config, or downloaded dependency is unavailable. Diagnostics identify the command/tool, page, fence line, cell ID, and field/path when applicable. dev tolerates a Haskell compiler/build failure so the documentation server remains available, but the affected cell displays the error until regeneration succeeds.

See Troubleshooting for recovery steps.