quillmark-cli 0.131.0

Command-line interface for Quillmark, a schema-driven document framework
quillmark-cli-0.131.0 is not a library.

Quillmark CLI

quillmark, the command-line interface to Quillmark: renders Markdown with card-yaml blocks through a quill into PDF, SVG, or PNG.

Maintained by borb-sh.

Installation

Each GitHub Release carries prebuilt binaries for Linux (x86_64, aarch64), macOS (Apple silicon, Intel) and Windows (x86_64). With cargo-binstall, the same binaries install by crate name:

cargo binstall quillmark-cli

From source, which needs a Rust toolchain:

cargo install quillmark-cli --locked

The binary lands at ~/.cargo/bin/quillmark. To build from a checkout instead:

cargo install --path crates/bindings/cli

quillmark --version prints the CLI's version and, in parentheses, the Typst release plates compile against.

Quick start

# Write a document to fill in: the quill's annotated blueprint
quillmark blueprint my_quill > document.md

# Render a document; output defaults to document.pdf
quillmark render my_quill document.md

# Omit the markdown file to render the quill's seeded document
quillmark render my_quill -o preview.pdf

# Every diagnostic a document draws; --strict fails on warnings too
quillmark check --strict my_quill document.md

# Pipe the artifact instead of writing a file
quillmark render my_quill document.md --stdout | lpr

my_quill is a quill directory, the one holding Quill.yaml. The Quickstart builds one.

Commands

Every command takes a <QUILL_PATH> pointing at a quill directory.

quillmark render [OPTIONS] <QUILL_PATH> [MARKDOWN_FILE]

Renders a document. With MARKDOWN_FILE omitted, the quill's seeded document is rendered instead, so a quill previews without any authored input.

  • -o, --output <FILE> — output path (default: the input filename with the format's extension)
  • -f, --format <FORMAT> — pdf, svg, or png; defaults to the -o extension when it names one, else pdf, and refuses one that disagrees with it
  • --ppi <PPI> — pixels per inch for png (default: 144); a page past 16384 px a side at it is refused, naming the ppi that fits; pdf and svg have no pixel ceiling
  • --stdout — write the artifact to stdout; all chatter moves to stderr
  • --output-data <DATA_FILE> — also write the compiled JSON data handed to the backend
  • --today <YYYY-MM-DD> — the render date: what a today date and a plate's datetime.today() render as (default: the local date)
  • --quiet — suppress warnings and the output-destination line

Warnings go to stderr, including one for each undeclared key or other input the page leaves out. A render that fails still prints the parse and validation warnings ahead of its error, and after them the backend's warnings from loading the quill, such as a package skipped for its manifest.

quillmark check [--strict] [--regions] <QUILL_PATH> <MARKDOWN_FILE>...

Checks documents against the quill's schema and prints every diagnostic. Without --regions it does not compile the plate. Exits 1 where a document draws an error; --strict exits 1 on any warning too, for CI. --regions renders each document that drew no error and lists the filled fields no click on the page reaches, and those only an enclosing field's region reaches; the list never moves the exit code.

quillmark schema <QUILL_PATH>

Prints the quill's field schema as YAML.

quillmark blueprint <QUILL_PATH>

Prints an annotated Markdown blueprint: a starting document with every declared field, each holding its default: or left empty (title: # string) where a value is expected.

quillmark validate <QUILL_PATH> [-v] [--no-render]

Loads the quill — Quill.yaml parse errors, default: literals against their declared types — checks referenced files, and renders the three canonical documents (the empty document, the blueprint, the seeded document) through the plate. -v prints each warning, such as a missing field description, where a plain run only counts them; --no-render skips the render. Exits 1 where the configuration is invalid or a canonical document does not render.

quillmark info <QUILL_PATH>

Prints the quill's identity from its quill: section, and its field, card and defaults counts.

quillmark workspace [OPTIONS] <QUILL_PATH> [MARKDOWN_FILE]

Writes what Typst's own tooling needs to compile a Typst quill's plate against one document (the generated helper package, the vendored packages, the fonts), then prints the typst watch command that compiles it. The helper holds that document's data: rerun workspace after the document changes. Typst reads files and packages a render refuses, and the installed typst can be another release than the embedded one, so a plate compiling there can still fail to render; the CLI reference lists the differences.

  • -o, --output <DIR> — workspace directory (default: quillmark-workspace)
  • --today <YYYY-MM-DD> — the render date: what a today date and, through the printed command's --creation-timestamp, a plate's datetime.today() render as (default: the local date)
  • --quiet — suppress warnings and the command line

Exit codes

0 on success, --help, and --version. 2 where argument parsing rejected the invocation before any command ran — an unknown flag, a missing argument, an unknown subcommand. 1 where the command ran and refused — an invalid quill, a missing file, a failed render, a failed check, an argument value the command itself rejects (-f docx). Diagnostics go to stderr.

Links

License

Licensed under the Apache License, Version 2.0. See LICENSE.