R RusDoxOne spec. Two trustworthy documents.

Reference

CLI reference

Render, validate, watch, benchmark, initialize, and configure documents.

View Markdown source

RusDox renders document specs into .docx and .pdf, validates them before render, can rebuild while you edit, and can benchmark the full pipeline.

Most Common Commands

Render one document:

rusdox mydoc.yaml

Render every spec in a folder:

rusdox examples

Create a starter YAML document:

rusdox init-doc mydoc.yaml

Validate a file before render:

rusdox validate mydoc.yaml

Rebuild on change with a local PDF/status dashboard:

rusdox dev mydoc.yaml --open

Benchmark a spec:

rusdox bench mydoc.yaml --iterations 5 --warmup 1

Generate DOCX, PDF, and parity evidence:

rusdox verify mydoc.yaml

Generate the authoring schema or migrate a legacy spec:

rusdox schema --output rusdox-spec-v1.schema.json rusdox migrate legacy.yaml --in-place rusdox migrate current.yaml --check

Parity Verification

Verify one file:

rusdox verify mydoc.yaml

Verify every top-level spec in a directory and write all artifacts under a CI workspace:

rusdox verify examples --output-root target/parity --format json

Add a deterministic rendered-page comparison:

rusdox verify mydoc.yaml \
  --visual-baseline tests/visual-baselines/mydoc \
  --visual-threshold 0.002

The command always writes versioned JSON and standalone HTML reports. Exit code 0 means parity passed, 1 means verification could not complete, and 2 means generated outputs failed one or more parity checks. See Parity verification for the complete contract and visual-diff boundary.

Validation

Check one file:

rusdox validate mydoc.yaml

Check every spec in a folder and emit JSON for CI:

rusdox validate examples --format json

Validation catches semantic issues before render, including unsupported spec versions, invalid colors, unknown style references, table shape mismatches, blank required values, and missing visual assets. File-backed semantic issues include one-based line and column coordinates in text and JSON reports.

Render commands also run the same semantic validation before they write output.

Schema and migration

The schema command prints the generated version 1 JSON Schema. Use --output for an atomic file write. The same object schema powers YAML, JSON, and TOML authoring and the bundled VS Code extension.

The migrate command prints a migrated spec by default. Use --in-place for an atomic replacement, --output for a separate destination, and --check in CI to reject legacy unversioned specs. RusDox rejects future versions instead of silently downgrading them. See Spec Versioning.

Development feedback loop

Start the recommended development loop:

rusdox dev mydoc.yaml --open

The loop binds only to 127.0.0.1. Its script-free dashboard refreshes to show the latest successful PDF, validation or parsing failure, per-stage timings, and absolute DOCX/PDF paths. A failed rebuild does not replace the previous successful artifact, so the preview remains useful while you repair the spec.

Tune polling and debounce for editors that save in several writes:

rusdox dev mydoc.yaml --poll-interval-ms 100 --debounce-ms 250

Use JSON Lines for tooling, or quiet mode for a bounded CI smoke check:

rusdox dev mydoc.yaml --json --port 0
rusdox dev mydoc.yaml --quiet --port 0 --max-builds 1

Each JSON build event includes status, trigger reason, changed paths, any error, timings, artifact paths, warnings, and dashboard URL. --port 0 asks the operating system for a free local port. --docx-only retains status and DOCX downloads while intentionally omitting PDF preview.

RusDox watches the input, active config, local includes, and asset paths. The terminal and dashboard identify the trigger as input, config, or asset/include.

The original rusdox watch command remains available for compatibility and now shares the debounced dependency watcher:

rusdox watch mydoc.yaml --docx-only --poll-interval-ms 250
rusdox watch examples --with-pdf

RusDox watches the spec input plus the active config path. Without --config, it tracks ./rusdox.toml and the user config fallback automatically.

Local integration protocol

Start the stable newline-delimited JSON worker. Stdout contains responses only:

rusdox serve stdio --output-root target/rusdox-output

For a local application that cannot own a child process, opt into the same contract over HTTP:

rusdox serve http --port 4175 --output-root target/rusdox-output

HTTP always binds to 127.0.0.1; requests go to POST /v1/request, and GET /health exposes only transport status. --max-requests bounds either transport for jobs and tests. See Integration protocol for the request schema, limits, output confinement, and executable language examples.

Benchmarking

Benchmark one spec:

rusdox bench mydoc.yaml --iterations 5 --warmup 1

Benchmark a folder and emit machine-readable output:

rusdox bench examples --format json

Isolate one pipeline for reproducible measurement:

rusdox bench mydoc.yaml --pipeline validation --iterations 5 --warmup 1
rusdox bench mydoc.yaml --pipeline docx --iterations 5 --warmup 1
rusdox bench mydoc.yaml --pipeline pdf --iterations 5 --warmup 1
rusdox bench mydoc.yaml --pipeline dual --iterations 5 --warmup 1
rusdox bench existing.docx --pipeline existing-docx --iterations 5 --warmup 1

Keep the generated artifacts instead of using a temporary output workspace:

rusdox bench mydoc.yaml --keep-output

Bench JSON reports include the pipeline, input SHA-256 and byte size, parse, validation, compose, DOCX write, PDF render, existing-DOCX open/save, total runtime, output byte sizes, and average/minimum/median/maximum summaries. The complete host and peak-memory protocol is documented in Reproducible Performance.

Word-native templates

Inspect placeholders and structural errors:

rusdox template inspect proposal.docx rusdox template inspect proposal.docx --format json

Render from JSON and generate the edited DOCX, native PDF, page snapshots, and parity report:

rusdox template render proposal.docx data.json --strict rusdox template verify proposal.docx data.json --strict --format json

Use --name for the artifact stem, --output-root for the complete evidence root, and --config for PDF renderer configuration. See Word-native Templates for syntax v1, strict behavior, loops, conditions, partials, preservation guarantees, and limitations.

Discover templates from the signed curated registry:

rusdox template list rusdox template search compliance rusdox template list --format json

Install one template or update installed entries:

rusdox template add board-report rusdox template update board-report rusdox template update --all

list and search do not write files. add and update verify the registry's detached Ed25519 signature, supported RusDox version, and the SHA-256 of the Word template and sample JSON before atomically installing them. Use --install-root for an explicit destination. Private registries can pass --registry with an HTTPS URL or local index and --public-key with the matching 32-byte key in hexadecimal. RusDox 1.x defaults to the immutable /registry/v1/index.json channel; the pre-1.0 channel remains online for old clients. See Curated template registry for the manifest, trust, privacy, and contribution contract.

Output Control

Write DOCX only:

rusdox mydoc.yaml --docx-only

Force PDF generation even if config disables it:

rusdox mydoc.yaml --with-pdf

Write a single input file to an explicit DOCX path:

rusdox mydoc.yaml --output ./out/custom-name.docx

Config Commands

Create a config:

rusdox config init --template

Launch the simple wizard:

rusdox config wizard --level basic

Launch the full wizard:

rusdox config wizard --level advanced

Print the active user config path:

rusdox config path

Print the effective config:

rusdox config show

Local Project Config

Create a local override:

rusdox config wizard --path ./rusdox.toml --level basic

That file overrides ~/rusdox/config.toml for the current project.

Other Supported Spec Formats

YAML is the recommended format, but these also work:

  • .yml
  • .json
  • .toml

Advanced Script Mode

RusDox also supports a .rs entrypoint for advanced workflows:

rusdox init-script mydoc.rs
rusdox mydoc.rs

This is useful when you need loops, conditional logic, API calls, or generated content that would be awkward in YAML.