Skip to content

CLI

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

OptionBehavior
--help, -hShow global or command-specific usage and exit successfully.
--versionPrint the installed Oxiquill package version.
--debugInclude 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.

CommandBehavior
init [directory]Create the versioned static starter. The current directory is the default.
devGenerate required runtimes, then run the watcher and Astro development server.
dev:runtimeRun only the runtime/source watcher.
dev:astroRun only Astro’s development server.
buildGenerate required runtimes, run checks, and create the static site.
previewPreview the existing production build.
check-linksCheck local routes and fragments in the existing built output without writing files.
checkGenerate required runtimes, synchronize Astro types, and run Astro diagnostics.
docgenSynchronize the manifest; --wasm dev | build also builds required runtimes.
cleanRemove only resolved Oxiquill-owned/generated and configured Astro output paths; preserve the verified download cache.
test-rustTest optional helper crates.
test-rust-coverageTest helper crates with the configured 85% coverage thresholds.
lint-rustCheck helper-crate formatting and run Clippy for all targets with warnings denied.
doc-rustBuild helper-crate documentation without dependencies.
test-wasmGenerate runtimes, run Rust defaults and declared tests, and retain unfiltered Haskell smoke checks.

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:

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

build, check, docgen, clean, and test-wasm hold one cross-process lock at <cacheDir>/runtime.lock for the whole command. build keeps it through runtime generation, Astro diagnostics, and the final Astro build. A standalone astro build holds the same lock from its build-start hook through build completion. The lock belongs to the consumer project and never writes into the installed Oxiquill package.

These five CLI commands accept --lock-timeout <seconds> before --. The default is 1800 seconds; 0 fails immediately if another process holds the lock. Values must be finite and nonnegative. For example:

Terminal window
pnpm exec oxiquill build --lock-timeout 60
pnpm exec oxiquill clean --lock-timeout 0

On contention, stderr identifies the holder’s command, PID, host, start time, and lock path. A reminder appears every 30 seconds. A timeout exits non-zero with the holder details and timeout value, without changing project files or generated artifacts; temporary acquisition records are removed. test-wasm --format json keeps stdout as NDJSON.

Development holds the lock only during initial generation or a watcher synchronization. Watchers wait without a timeout, combine pending changes, and synchronize the latest inputs once the lock becomes available. check --watch holds its lock for the command’s lifetime.

Clean preserves the cache directory, its ownership marker, and active lock coordination files while removing generated contents. Normal completion and SIGINT/SIGTERM release owned locks. A dead same-host PID can be reclaimed automatically; lock age alone never permits reclamation. See lock recovery for unknown or foreign-host owners.

In the Oxiquill repository, pnpm build builds the reusable package incrementally and reuses unchanged runtime artifacts. Astro recreates its static output directory on every build. pnpm build:package incrementally builds only the package; packing always performs a clean package build.

Run the repository’s pnpm build:clean to clean and rebuild the package, generated runtimes, and site while preserving the verified download cache. In a consumer project, run oxiquill clean followed by oxiquill build for a clean runtime/site rebuild.

Rust and Haskell rebuilds reuse compiler caches under cacheDir/build-cache. Haskell caches are separated by mode and compiler version. An explicit CARGO_TARGET_DIR is respected for both Wasm builds and tests. Clean removes Oxiquill-owned compiler caches, preserves verified downloads, and leaves external user-owned Cargo targets alone. Published runtime files are checked against recorded sizes and SHA-256 hashes before reuse.

oxiquill build --force only clears Astro’s content cache. It does not force a package rebuild or discard Oxiquill runtime fingerprints.

Terminal window
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.

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.

Terminal window
pnpm exec oxiquill test-wasm --page guides/validation.mdx --cell tested-square --case default --format json
OptionBehavior
--page <path>Repeatable docs-relative Markdown/MDX path. Normalizes separators and . segments; absolute paths and escaping the docs directory are rejected.
--cell <id>Repeatable scoped cell id. A page-local id is accepted with exactly one --page.
--case <id>Repeatable filter for default or a named case. Untested named cases require --all-cases.
--all-casesAlso execute each untested authored case as a smoke check.
--format human|jsonHuman lines by default, or NDJSON events on stdout. Compiler and generation progress goes to stderr.

Repeated values within an option are alternatives; page, cell, and case filters intersect. Every selector must match, and an empty selection is a usage error. Explicitly selecting a non-Rust cell reports that case tests are not yet supported for its language. Filtered runs skip the legacy Haskell smoke step.

Without selectors, all Rust defaults and declared tests run. Every cell/case executes once: declared expectations replace its smoke check. The harness reuses the existing generated Wasm build, compiles its module once, and initializes a fresh instance for each execution. It does not compile a separate test build.

JSON output emits test events with page, line (fence line), cell, case, status (pass or fail), durationMs, and failures. Each failure includes reason, fieldPath, location (line, column), bounded actual and expected strings, and path/artifact when applicable. Failure reasons distinguish execution errors, timeouts, harness errors, missing paths/artifacts, and failed comparisons. Fatal errors emit a diagnostic event with message. The final summary event has total, passed, failed, exitStatus, and an optional haskell object with status and cellCount. Haskell counts are separate from Rust test totals.

{
"type": "test",
"page": "guides/validation.mdx",
"line": 109,
"cell": "guides__validation__tested-square",
"case": "default",
"status": "pass",
"durationMs": 1,
"failures": []
}
{ "type": "summary", "total": 1, "passed": 1, "failed": 0, "exitStatus": 0 }

Exit status is 0 when everything passes and 1 for failed tests, timeouts, invalid authoring, or usage errors. An unfiltered zero-cell project succeeds; unmatched selectors never succeed silently. See Validation for metadata and assertion forms.

build, check, and docgen accept --format human|json (default: human) and --explain:

Terminal window
pnpm exec oxiquill build --explain
pnpm exec oxiquill docgen --wasm dev --format json
pnpm exec oxiquill check --explain --format json

Explain resolves configuration, discovers and validates cells, and evaluates the same runtime plan without taking the runtime lock. It writes no artifacts, downloads nothing, and starts only toolchain version probes. build plans release artifacts, check plans development artifacts, and docgen --wasm dev|build selects the desired runtime mode. Configuration or cell validation failures exit nonzero. Unavailable toolchain probes are reported without running a build. Execution-only options such as --outDir, --watch, --force, and --lock-timeout cannot be combined with explain.

Human output reports phase boundaries, plan reasons, and a final phase summary. Child stdout/stderr are forwarded immediately. After 30 seconds without child output, a heartbeat identifies the phase and language/module; it repeats every 30 seconds of silence and stops when the process ends. There are no percentages or completion-time estimates.

JSON output is NDJSON on stdout. Every line is one event, child output is wrapped, and the final event is always a summary, including on failure:

typeFields
phasephase, state, elapsedMs; optional language, module, cache (hit or miss), and reason. States: start, success, failure, skipped.
planlanguage, action, reasons; applicable module, key, pages, and target (source or public).
heartbeatphase, elapsedMs; applicable language and module.
outputsource (tool), stream (stdout or stderr), line.
diagnosticmessage.
summaryexitStatus, phases: one row per phase with phase, state, elapsedMs, and cache: { hits, misses }.

The phases are discovery, validation, generation, compile, optimize, publish, astro-check, and astro-build. Optimization events come from Oxiquill’s own optimizer operation and include verified optimizer-cache reuse. Summary durations aggregate operations within each phase.

Plan reasons use code: source-changed (with changes: [{ page, cell }]), helper-inputs-changed, toolchain-changed, build-options-changed (with changed variables names only), generator-changed, package-changed, dependencies-changed, mode-upgrade, output-missing, integrity-mismatch, previous-build-failed, failure-unchanged, or forced. cache-hit describes verified reuse; absent describes an already absent language. Fingerprints and build-option values are never printed. No telemetry or benchmark history is stored.

Terminal window
pnpm exec oxiquill check-links
pnpm exec oxiquill check-links --format json
pnpm exec oxiquill build --check-links

check-links reads <cacheDir>/build-report.json and the existing rendered HTML. It writes no files, takes no runtime lock, and never regenerates runtimes. Run oxiquill build first if the report or output is missing. The report records the completed build’s output directory, site URL, base, trailing-slash policy, build format, and redirects; a custom build --outDir is respected on subsequent checks.

The checker validates href on anchors and image-map areas against local pages and assets. HTML fragments match rendered id attributes or legacy anchor name attributes, including generated cell and ox-ref-* anchors. Fragments are percent-decoded; empty fragments and #top always pass. Query strings do not affect file lookup. Non-HTML assets are checked only for existence.

Relative paths resolve against the referring page’s URL. Same-site absolute URLs within the configured base are checked; other hosts and same-site absolute URLs outside the base are skipped. Relative and root-relative paths outside the base fail. External links and schemes such as mailto:, tel:, data:, javascript:, and blob: are never fetched. Configured and rendered HTML redirects are followed, with fragments checked on the final target.

Failures distinguish missing-page, missing-fragment, outside-base, redirect-loop, and trailing-slash. Explicit trailingSlash: 'always' and 'never' policies apply to page routes. Repeated failures are grouped by resolved target and reason, retaining a total occurrence count and up to five example referring pages with their original href values.

--format human|json defaults to human. JSON output is NDJSON: each link-failure event contains target, reason, count, and examples (objects with source and href). The final summary contains exitStatus and linkCheck totals: pages, checked, skipped, failures (distinct groups), and occurrences (all failed links). Fatal input errors emit a diagnostic and a final summary without link totals.

Exit status is 0 for a clean site and 1 for broken links or invalid inputs. build --check-links runs the same checker after a successful build and adds link totals to the existing build summary. Broken links make it fail while keeping the output available for inspection. Plain build does not check links. --check-links cannot be combined with --explain.