slide-cli

A TypeScript CLI to create beautiful slide cards from JSON data + HTML templates. Supports 9:16 (Stories/Reels), 16:9 (presentations/YouTube), and 1:1 (feed) aspect ratios.

slide create        --data ./templates/minimal/sample.json --template minimal --out ./output
slide list          [--verbose]
slide add-template  <path>  [--force]

Installation

From npm (end users)

npm install -g slide-cli
slide --help

Requires: Node.js ≥ 18 · Chrome/Chromium (bundled via Puppeteer)

From source (contributors)

git clone https://github.com/doum1004/slide-cli.git
cd slide-cli
bun install       # Bun is required for building and running tests
bun run build     # outputs to dist/
npm link          # exposes the `slide` command globally
slide --help

Requires: Bun ≥ 1.0 (build + test only) · Node.js ≥ 18 (runtime)

Why both Bun and Node?

The published dist/ runs on Node — so any end user with Node can install and use slide via npm without touching Bun. Bun is only needed locally to build (bun build) and run tests (bun test). This avoids the Windows issue where npm link detected Bun and generated a .ps1 wrapper that caused Puppeteer to hang silently.

Quick start (from source)

bun install
bun run build
slide list --verbose
slide create --data ./templates/minimal/sample.json --template minimal 

Commands

slide create

slide create --data ./templates/minimal/sample.json --template minimal --out ./output

| Flag | Default | Description | |---|---|---| | -d, --data <file> | (required) | Path to data JSON | | -t, --template <id> | (required) | Template id or name | | -o, --out <dir> | ./output | Output directory | | -f, --format <png\|jpg> | jpg | Screenshot format | | --no-images | off | Skip screenshots (HTML only) | | --allow-missing-images | off | Render slides without unresolvable image slots instead of aborting |

Output:

output/
├── slide-1.html   slide-1.jpg
├── slide-2.html   slide-2.jpg
│   …
├── index.html     ← presentation viewer
├── data.json      ← copy of your input
└── manifest.json  ← machine-readable index (slideIndex, htmlPath, imagePath)

Backends and agents should read manifest.json to get the ordered image paths:

const manifest = JSON.parse(fs.readFileSync(`${outDir}/manifest.json`, "utf-8"));
const images = manifest.slides
  .filter(s => s.imagePath)
  .map(s => path.join(outDir, s.imagePath));

slide list

slide list
slide list --verbose    # full slot schema

slide add-template

slide add-template ./my-template/
slide add-template ./my-template/ --force

Data JSON format

{
  "title": "My Presentation",
  "slides": [
    {
      "layout": "minimal",
      "heading": "Less is more",
      "body": "Simplicity is the ultimate sophistication.",
      "label": "Chapter 01",
      "accent": "#c8b89a",
      "bg": "#0f0e0c"
    }
  ]
}

Built-in templates

| id | Ratio | Required slots | Style | |---|---|---|---| | minimal | 9:16 | heading | Dark typographic, Fraunces serif | | bold-title | 9:16 | title | Gradient editorial, Bebas Neue | | quote-card | 9:16 | quote | Light serif pull-quote card | | minimal-wide | 16:9 | heading | Dark typographic, two-column layout | | bold-title-wide | 16:9 | title | Gradient editorial, title left / subtitle right | | quote-card-wide | 16:9 | quote | Light serif pull-quote, quote left / attribution right |

Creating a custom template

my-template/
├── template.json    ← manifest + slot definitions
└── template.html    ← Handlebars HTML at your chosen dimensions

template.json

Set aspectRatio, width, and height to match your target format:

| aspectRatio | width | height | Use case | |---|---|---|---| | "9:16" | 1080 | 1920 | Instagram Stories, TikTok, Reels | | "16:9" | 1920 | 1080 | YouTube thumbnails, presentations | | "1:1" | 1080 | 1080 | Instagram feed, Twitter/X |

{
  "name": "My Template",
  "id": "my-template",
  "version": "1.0.0",
  "description": "Short description",
  "aspectRatio": "16:9",
  "width": 1920,
  "height": 1080,
  "slots": [
    { "id": "headline", "type": "text",  "label": "Headline",   "required": true },
    { "id": "bg",       "type": "color", "label": "Background", "required": false, "default": "#fff" }
  ]
}

Slot types: text · color · image · number · url

template.html

Match width and height in CSS to the values in your manifest:

<!DOCTYPE html><html>
<head><style>
  html, body { width: 1920px; height: 1080px; background: {{bg}}; }
</style></head>
<body>
  <h1>{{headline}}</h1>
  {{#if subtitle}}<p>{{subtitle}}</p>{{/if}}
  <footer>{{slideIndex}} / {{totalSlides}}</footer>
</body></html>

Always available: {{slideIndex}} · {{totalSlides}} · {{title}}
Helpers: {{#if}} · {{upper val}} · {{lower val}} · {{default val "fallback"}}

Presentation viewer

The generated index.html has:

• ← → keys or buttons · Space = autoplay · F = fullscreen
• Home/End · touch/swipe support
• Speed selector · progress bar · dot nav

Template storage

| Path | Purpose | |---|---| | ~/.slide-cli/templates/ | User templates (via add-template) | | <install>/dist/templates/ | Built-in templates (shipped with the package) |

User templates take priority over built-ins on id collision.

Docker

Production (installs from npm):

docker build -t slide-cli .
docker run --rm -v $(pwd)/output:/work/output slide-cli \
  slide list
docker run --rm -v $(pwd)/output:/work/output slide-cli \
  slide create --data ./templates/minimal/sample.json --template minimal

Local dev (installs from local build):

bun run build
docker build -f Dockerfile.dev -t slide-cli-dev .