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 install -g stellardeck
npx playwright install chromium   # one-time: the headless renderer
stellardeck --help                # full reference

Working from a repo checkout instead? Every command below also works as npm run export -- <args>.

Live Modes

Preview

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

stellardeck --preview talk.md

Serve

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

stellardeck --serve
stellardeck --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

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

Validation

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

stellardeck --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.

stellardeck --list-themes                # JSON array of theme names
stellardeck --list-schemes nordic        # JSON array of schemes for "nordic"

Slide Selection

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

stellardeck --slides 1-5 talk.md         # slides 1 through 5
stellardeck --slides 1,3,5 talk.md       # slides 1, 3, and 5
stellardeck --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

stellardeck --theme ostrich --scheme 2 --autoflow --scale 3 talk.md

Batch Mode

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

stellardeck --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.

stellardeck --input-dir decks --output dist --grid --grid-cols 3

Stdin Input

Pipe markdown by passing - as the input:

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

JSON Output

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

stellardeck --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

stellardeck --png --slides 1 --scale 1 talk.md ./thumb

Deck overview card

stellardeck --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" \
  | stellardeck --pdf --autoflow - out.pdf

Agent workflow with warning handling

result=$(stellardeck --json --pdf slides.md)

if echo "$result" | jq -e '.warnings | any(contains("overflow"))' > /dev/null; then
  echo "Overflow detected — re-exporting with autoflow"
  stellardeck --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.