CLI Reference

Complete reference for all CLI commands and flags.

`grafex init`

Scaffold the minimal setup to start writing compositions. Run this in a new project after npm install grafex.

bash

grafex init

Creates two files in the current directory:

tsconfig.json — TypeScript config with the correct JSX settings for Grafex
composition.tsx — A starter composition with a "Hello, Grafex!" example

If either file already exists, it is skipped without error.

Flags

Flag	Short	Description
`--help`	`-h`	Show help text

`grafex export`

Render a composition file to an image.

bash

grafex export -f <file> [options]

Flags

Flag	Short	Type	Default	Description
`--file`	`-f`	string	`—`	Path to the .tsx composition file (required)
`--out`	`-o`	string	`./output.png`	Output file path or directory (for multi-variant output)
`--props`	`—`	string (JSON)	`{}`	Props to pass to the composition as a JSON object
`--width`	`—`	number	`from config`	Override composition width in pixels
`--height`	`—`	number	`from config`	Override composition height in pixels
`--scale`	`—`	number	`1`	Device pixel ratio — 2 for retina/high-DPI output
`--format`	`—`	string	`png`	Output format: png or jpeg
`--quality`	`—`	number	`90`	JPEG quality 1–100 (only applies when format is jpeg)
`--browser`	`—`	string	`webkit`	Browser engine: webkit or chromium
`--variant`	`—`	string	`(all)`	Render a single variant by name. Omit to render all variants.
`--help`	`-h`	—		Show help text

Examples

Basic export:

bash

grafex export -f card.tsx -o card.png

Pass props to a composition:

bash

grafex export -f card.tsx -o card.png --props '{"title":"Hello World","author":"Jane"}'

Override dimensions:

bash

grafex export -f card.tsx -o card.png --width 800 --height 400

Export to a specific directory:

bash

grafex export -f card.tsx -o ./images/card.png

Export at 2x resolution (retina):

bash

grafex export -f card.tsx -o card@2x.png --scale 2

Export as JPEG:

bash

grafex export -f card.tsx -o card.jpg --format jpeg

Export as JPEG with custom quality:

bash

grafex export -f card.tsx -o card.jpg --format jpeg --quality 80

Export all variants (when config.variants is defined):

bash

grafex export -f card.tsx

Export all variants to a directory:

bash

grafex export -f card.tsx -o ./images/

Export a single variant:

bash

grafex export -f card.tsx --variant twitter -o twitter.png

Exit codes

Code	Meaning
`0`	Success — image exported
`1`	Error — composition failed to render (check stderr for details)

`grafex dev`

Start a live preview server that watches your composition and re-renders on every file change.

bash

grafex dev -f <file> [options]

Flags

Flag	Short	Type	Default	Description
`--file`	`-f`	string	`—`	Path to the .tsx composition file (required)
`--port`	`—`	number	`3000`	Preview server port
`--props`	`—`	string (JSON)	`{}`	Props to pass to the composition as a JSON object
`--variant`	`—`	string	`(first)`	Show only the named variant (when composition has variants)
`--help`	`-h`	—		Show help text

The dev server watches the composition file, all its imports, CSS files from config.css, and local image assets. Changes are debounced and the preview updates within ~100ms. Open http://localhost:3000 to see the live preview. Press Ctrl+C to stop.

Global Flags

grafex --version    # Print version and exit
grafex --help       # Print help text and exit