CLI Tool

Overview

The @glyphjs/cli package provides a command-line interface for working with GlyphJS documents outside of a browser. You can lint documents for errors, compile Markdown to IR, render UI blocks as PNG screenshots, export to HTML/PDF/DOCX, and run a live-reload dev server.

Installation

npm

npm install -g @glyphjs/cli

pnpm

pnpm add -g @glyphjs/cli

npx (no install)

npx @glyphjs/cli compile document.md

Requirements: Node.js 20 or later.

Commands

lint

Validate ui: blocks in a Markdown file and report diagnostics. Designed for use in CI pipelines, pre-commit hooks, and LLM tool loops.

glyphjs lint document.md

Flag	Description	Default
--format <fmt>	Output format: text or json	text
--strict	Treat warnings as errors (exit 1)
-q, --quiet	Suppress output — rely on exit code only

Exit codes:

Code	Meaning
0	No errors (warnings are OK unless --strict)
1	One or more errors
2	Could not read the input file

Examples:

# Check a file and print human-readable diagnostics
glyphjs lint document.md

# Machine-readable output for LLM tool use or CI pipelines
glyphjs lint document.md --format json

# Fail on warnings too (for strict CI)
glyphjs lint document.md --strict

# Silent check — only exit code matters
glyphjs lint document.md --quiet && echo "clean"

# Pipe a block from stdin
echo '```ui:chart
type: bar
series: []
```' | glyphjs lint - --format json

JSON output shape:

{
  "valid": false,
  "file": "document.md",
  "errorCount": 1,
  "warningCount": 0,
  "diagnostics": [
    {
      "severity": "error",
      "code": "YAML_PARSE_ERROR",
      "message": "YAML parse error in ui:chart: ...",
      "source": "parser",
      "position": { "start": { "line": 5, "column": 1 }, "end": { "line": 10, "column": 3 } }
    }
  ]
}

schemas

Output the JSON Schema for any GlyphJS component type. Useful for LLM-assisted document generation, IDE validation, and CI schema checks.

glyphjs schemas chart

Flag	Description
--all	Output all 32 component schemas as a single JSON object
--list	List available component type names, one per line
-o, --output <path>	Write output to file instead of stdout

Exit codes:

Code	Meaning
0	Success
2	Unknown type or I/O error

Examples:

# Schema for a single component (type prefix is optional)
glyphjs schemas chart
glyphjs schemas ui:chart    # same output

# List all 32 available types
glyphjs schemas --list

# Dump all schemas to a file for offline use
glyphjs schemas --all -o schemas.json

# Pipe a single schema to a validator
glyphjs schemas table | jq '.properties | keys'

JSON output shape (single type):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "series": { "type": "array", "items": { ... } }
  },
  "required": ["series"]
}

JSON output shape (--all):

{
  "ui:chart": { "$schema": "...", "type": "object", ... },
  "ui:table": { "$schema": "...", "type": "object", ... }
}

themes

List all bundled themes shipped with the CLI.

glyphjs themes

Prints the available theme names and usage instructions. Pass any listed name to --theme on render, export, or serve.

Example output:

Available bundled themes:

  warmcraft

Usage:  glyphjs export doc.md --format html --theme <name>
        glyphjs serve doc.md --theme <name>
        glyphjs render doc.md --theme <name>

compile

Compile a Markdown file to GlyphJS IR (JSON).

glyphjs compile document.md -o output.json

The compile command parses your Markdown, extracts ui: fenced code blocks, validates the YAML data against component schemas, and outputs the intermediate representation as JSON.

Flag	Description	Default
-o, --output <path>	Write JSON to file instead of stdout	stdout
--compact	Output minified JSON
-v, --verbose	Show diagnostics on stderr

Examples:

# Compile and pretty-print to stdout
glyphjs compile document.md

# Compile to a file with minified output
glyphjs compile document.md -o ir.json --compact

# Pipe from stdin
cat document.md | glyphjs compile -

render

Render ui: blocks from a Markdown file to PNG screenshots.

glyphjs render document.md -d ./screenshots/

Each ui: block in the document is rendered in a headless Chromium browser and saved as a high-DPI PNG image.

Flag	Description	Default
-o, --output <path>	Output file or directory	<stem>-<blockId>.png
-d, --output-dir <dir>	Output directory for screenshots
-t, --theme <theme>	Base theme light/dark, or a bundled theme name (run glyphjs themes to list)	light
--theme-file <path>	YAML file with custom theme variables
-b, --block-id <id>	Render only this block	all blocks
-w, --width <px>	Viewport width in pixels	1280
--viewport-height <px>	Viewport height in pixels	800
--device-scale-factor <n>	Device scale factor for HiDPI	2
-v, --verbose	Show progress on stderr

Examples:

# Render all blocks to a directory
glyphjs render document.md -d ./screenshots/

# Render a single block
glyphjs render document.md -b chart-1 -o hero-chart.png

# Render with a bundled theme
glyphjs render document.md -d ./out/ --theme warmcraft

Prerequisite

The render command requires Playwright. Install it with:

npm install playwright

export

Export a Markdown file to HTML, PDF, Markdown, or DOCX.

glyphjs export document.md --format html -o output.html

Flag	Description	Default
--format <fmt>	Output format: html, pdf, md, docx	(required)
-o, --output <path>	Write to file instead of stdout	stdout
-t, --theme <theme>	Base theme light/dark, or a bundled theme name (run glyphjs themes to list)	light
--theme-file <path>	YAML file with custom theme variables
-w, --width <px>	Document width in pixels	800
--viewport-height <px>	Viewport height in pixels	1024
--max-width <css>	Maximum content column width, e.g. 64rem or none	64rem
--title <title>	Override document title
--page-size <size>	PDF page size (e.g. Letter, A4)	Letter
--margin <margin>	PDF margin in CSS shorthand	1in
--padding <padding>	Document content padding in CSS shorthand
--landscape	Use landscape orientation for PDF
--continuous	PDF: render as one tall page with no page breaks
--device-scale-factor <n>	Device pixel ratio for block images (md export)	2
--images-dir <dir>	Directory for rendered block images (md export)	./images/
-v, --verbose	Show diagnostics on stderr

Format details:

• html — Self-contained HTML with inlined CSS and server-rendered components. No external dependencies.
• pdf — Renders components via Playwright, then prints to PDF. Requires Playwright.
• md — Replaces ui: blocks with PNG screenshots and outputs clean Markdown. Requires Playwright.
• docx — Converts via Pandoc. UI blocks are rendered as images and embedded. Requires Playwright and Pandoc.

Examples:

# Export to a styled HTML file using a bundled theme
glyphjs export document.md --format html -o report.html --theme warmcraft

# Export to PDF with A4 pages
glyphjs export document.md --format pdf -o report.pdf --page-size A4

# Export to Markdown with images in a custom directory
glyphjs export document.md --format md -o README.md --images-dir ./assets/

# Export to DOCX
glyphjs export document.md --format docx -o report.docx

serve

Start a development server with live reload.

glyphjs serve document.md

The server compiles your Markdown to HTML and serves it on localhost. When you edit the source file, the browser reloads automatically via Server-Sent Events.

Flag	Description	Default
-p, --port <port>	Port to listen on	3000
-t, --theme <theme>	Base theme light/dark, or a bundled theme name (run glyphjs themes to list)	light
--theme-file <path>	YAML file with custom theme variables
--open	Open browser on start
-v, --verbose	Show diagnostics on stderr

Examples:

# Start with defaults on port 3000
glyphjs serve document.md

# Custom port and auto-open browser
glyphjs serve document.md --port 8080 --open

# Serve with a bundled theme
glyphjs serve document.md --theme warmcraft -v

Custom Themes

You can customize the appearance of all components by providing a YAML theme file. The file specifies a base theme to extend and a set of CSS custom property overrides:

base: light   # or "dark"

variables:
  --glyph-accent: "#F56400"
  --glyph-surface: "#F5EDE4"
  --glyph-border: "#E0D6CC"

Every --glyph-* CSS custom property can be overridden. See the Theme Variables reference for the full list.

Pass your theme file to any command:

glyphjs export document.md --format html --theme-file my-theme.yaml -o styled.html
glyphjs serve document.md --theme-file my-theme.yaml
glyphjs render document.md --theme-file my-theme.yaml -d ./screenshots/

Bundled Themes

The CLI ships with 12 community themes you can use directly or as starting points:

File	Description
catppuccin-mocha.yml	Catppuccin Mocha — muted pastels on deep dark background
dracula.yml	Dracula — vivid purple & pink on dark gray
github-dark.yml	GitHub Dark — GitHub’s dark mode palette
github-light.yml	GitHub Light — GitHub’s light mode palette
gruvbox.yml	Gruvbox — retro warm browns, yellows, and greens
monokai.yml	Monokai — vivid greens and oranges on near-black
night-owl.yml	Night Owl — deep blues with warm accent tones
nord.yml	Nord — Arctic blues and cool grays
one-dark.yml	One Dark — Atom’s One Dark Pro palette
solarized-dark.yml	Solarized Dark — precision colors, dark variant
solarized-light.yml	Solarized Light — precision colors, light variant
tokyo-night.yml	Tokyo Night — deep navy with vibrant neons

Use a bundled theme by name with the --theme flag:

# List available themes
glyphjs themes

# Use a bundled theme directly — no path needed
glyphjs export document.md --format html --theme warmcraft -o output.html
glyphjs serve document.md --theme warmcraft
glyphjs render document.md --theme warmcraft -d ./screenshots/

--theme-file always takes precedence if both flags are provided, allowing you to use a bundled theme as a starting point and override it:

glyphjs export document.md --format html \
  --theme warmcraft \
  --theme-file my-overrides.yaml \
  -o output.html

Prerequisites

Different commands have different external dependencies:

Command / Format	Dependency	Install
render	Playwright	npm install playwright
export --format pdf	Playwright	npm install playwright
export --format md	Playwright	npm install playwright
export --format docx	Playwright + Pandoc	npm install playwright + pandoc.org
lint, compile, schemas, themes, serve, export --format html	None	Built-in