CLI Tool

The gridwell CLI converts table IR files to any supported format.

Installation

cargo install gridwell-cli

Commands

gridwell convert

Convert a table IR JSON file to an output format. The input is validated first; if it is invalid, the validation errors are printed to stderr, nothing is written, and the exit code is 1.

gridwell convert [OPTIONS] --to <FORMAT> [INPUT]
gridwell convert [OPTIONS] -o <FILE> [INPUT]

Arguments:

  • [INPUT] — Input file path (use - or omit for stdin)

Options:

  • -t, --to <FORMAT> — Output format (see gridwell formats); required unless -o is given, when it is inferred from the file extension
  • -o, --output <FILE> — Output file (defaults to stdout for text; required for binary). The extension picks the format: .html, .tex, .typ, .rtf, .svg, .txt (ansi), .docx, .xlsx, .pptx. .json is both pandoc and quarto, so it needs --to; --to always wins over the extension. A .txt (ansi) file is plain text unless the options set "color": true
  • -O, --options <JSON> — Writer options as a JSON object
  • --options-file <FILE> — Read writer options from a JSON file

Examples:

# Render to HTML (stdout)
gridwell convert table.json --to html

# Render to file (format from the extension)
gridwell convert table.json -o table.tex

# Binary format requires -o
gridwell convert table.json -o report.docx

# .json needs --to
gridwell convert table.json --to quarto -o table.json

# Writer options
gridwell convert table.json --to html --options '{"inline_styles": true}'


# From stdin
cat table.json | gridwell convert --to html

# Pipe through other tools
gridwell convert table.json --to html | pbcopy

gridwell validate

Check an IR file for structural errors. Exits with code 0 if valid, code 1 if errors found.

gridwell validate [INPUT]
Example output
$ gridwell validate valid_table.json
Valid: no errors found.

$ gridwell validate broken_table.json
Found 2 validation error(s):
  - [COL_COUNT] tbody group 0 row 0 has 4 cells but config.table_cols is 3
  - [SPAN_OVERFLOW_RIGHT] cell at (row=1, col=3) has colspan=2 but table has 3 columns

gridwell formats

List all supported output formats.

Example output
$ gridwell formats
Supported output formats:

  Text formats:
    html     HTML5 table (.html)
    latex    LaTeX tabular / longtable (booktabs) (.tex)
    typst    Typst table markup (.typ)
    rtf      Rich Text Format (.rtf)
    svg      SVG image (standalone, measured layout) (.svg)
    ansi     Terminal output with box drawing and ANSI colors (.txt)
    pandoc   Pandoc JSON AST (Table block) (.json)
    quarto   Quarto-flavored Pandoc JSON AST (cross-referenceable Div) (.json)

  Binary formats:
    docx     Microsoft Word document (.docx)
    xlsx     Microsoft Excel workbook (.xlsx)
    pptx     Microsoft PowerPoint slide (.pptx)

Pass writer options with --options '<JSON>'; see `gridwell formats --json`.

gridwell formats --json prints the same list as JSON, including each format’s extension, media type, and options with their defaults.

Format Values

Format names are case-insensitive. An unknown name is an error that lists the supported ones.