Command Line

StellarDeck’s CLI runs the same rendering engine as the desktop app, headless via Playwright. Use it for exports, live preview, validation, batch processing, or agent workflows.

npm run export -- --help    # full reference
npm run export -- -h        # same thing

Live Modes

Preview

Open a deck in the browser for viewing. Starts a temporary server, opens the default browser, and waits. Ctrl+C stops.

npm run export -- --preview talk.md

There’s also a shortcut:

npm run preview -- talk.md

Serve

Start a dev server and open the viewer in the browser. Watches for file changes. Ctrl+C stops.

npm run export -- --serve
npm run export -- --serve --port 8080

Export Formats

Pick one format per invocation. Default is --pdf.

Flag	Output	Use case
--pdf	Single PDF file	Share, print, send
--png	Directory with one PNG per slide (001.png, 002.png…)	Thumbnails, social media
--grid	Single composite image of all slides	Deck overview, preview cards

npm run export -- talk.md                          # → talk.pdf (default)
npm run export -- --pdf talk.md ~/Desktop/talk.pdf # explicit output path
npm run export -- --png talk.md ~/Desktop/slides   # → ~/Desktop/slides/001.png...
npm run export -- --grid talk.md overview.png      # → overview.png
npm run export -- --grid --grid-cols 3 talk.md     # 3-column grid

The npm run pdf shortcut exists for the common case:

npm run pdf -- talk.md

Validation

Render a deck and collect diagnostics without exporting anything. Returns JSON with slide count and warnings.

npm run export -- --validate talk.md

Output:

{
  "ok": true,
  "slides": 23,
  "totalSlides": 23,
  "warnings": [
    "content overflow on slide 2 (text may be clipped — consider [.autoscale: true])",
    "image failed to load: /assets/missing.webp"
  ]
}

Theme Introspection

List available themes and their color schemes. No browser needed.

npm run export -- --list-themes                # JSON array of theme names
npm run export -- --list-schemes nordic        # JSON array of schemes for "nordic"

Slide Selection

Use --slides to export a subset. Accepts ranges, lists, or both:

npm run export -- --slides 1-5 talk.md         # slides 1 through 5
npm run export -- --slides 1,3,5 talk.md       # slides 1, 3, and 5
npm run export -- --slides 1-3,7,9 talk.md     # mixed

Slides are 1-indexed. Out-of-range slides produce warnings but don’t fail the export.

Rendering Options

Override deck settings without editing the markdown:

Flag	Default	Description
--scale <n>	2	DPI scale factor (1 = 72dpi, 2 = 144dpi, 3 = 216dpi)
--theme <name>	deck default	Override theme (e.g. nordic, ostrich, fira)
--scheme <n>	deck default	Override color scheme number
--autoflow	off	Enable autoflow layout inference
--port <n>	3032	Dev server port

npm run export -- --theme ostrich --scheme 2 --autoflow --scale 3 talk.md

Batch Mode

Export an entire directory tree. Output mirrors the input structure:

npm run export -- --input-dir ./decks --output ./dist

decks/intro.md          → dist/intro.pdf
decks/talks/keynote.md  → dist/talks/keynote.pdf

Works with any format and inherits all rendering options. The browser and dev server are reused across files.

npm run export -- --input-dir decks --output dist --grid --grid-cols 3

Stdin Input

Pipe markdown by passing - as the input:

echo "# Hello\n---\n# World" | npm run export -- --pdf - hello.pdf
cat draft.md | npm run export -- --png - ./thumbs

JSON Output

Use --json for machine-readable output (implicit for --validate, --list-themes, --list-schemes):

npm run export -- --json --pdf talk.md

Success:

{
  "ok": true,
  "format": "pdf",
  "output": "/path/to/talk.pdf",
  "files": null,
  "slides": 23,
  "totalSlides": 23,
  "bytes": 1847293,
  "warnings": []
}

Error:

{
  "ok": false,
  "error": "File not found: nonexistent.md"
}

The files field contains an array of paths for --png mode, null otherwise. Exit code is 1 on error.

Warnings

Exports succeed even when problems are detected. Warnings surface issues for agents or pipelines to react to:

Warning	Cause
content overflow on slide N	Text/elements extend past the 1280x720 frame
image failed to load: <url>	Image returned 4xx/5xx or network error
slide N out of range	--slides specified a slide past the deck’s end
theme "X" not applied	Theme name not recognized

Recipes

Title slide thumbnail

npm run export -- --png --slides 1 --scale 1 talk.md ./thumb

Deck overview card

npm run export -- --grid --grid-cols 3 --slides 1-9 talk.md card.png

Generate from LLM output

claude "write a 5-slide deck about X in Deckset markdown" \
  | npm run export -- --pdf --autoflow - out.pdf

Agent workflow with warning handling

result=$(npm run export -- --json --pdf slides.md)

if echo "$result" | jq -e '.warnings | any(contains("overflow"))' > /dev/null; then
  echo "Overflow detected — re-exporting with autoflow"
  npm run export -- --json --pdf --autoflow slides.md
fi

How It Works

The CLI launches headless Chromium via Playwright, loads the same viewer.html the desktop app uses, renders each slide, and captures it. PDF mode composes via pdf-lib; PNG writes individual files; grid composes via sharp. The same code that powers the in-app export button runs here.