Docs

CLI Reference

The SuperImg CLI handles everything from scaffolding projects to rendering final media.

Installation

npm install -g superimg

Or use via npx without installing:

npx superimg <command>

Commands

superimg new

Create a new template in the current project.

superimg new my-video

This creates:

my-video/
├── my-video.media.ts    # Your template
└── _config.ts           # Settings (dimensions, fps, duration)

Options:

superimg new my-video --compose     # Multi-scene template (intro/content/outro)
superimg new my-video --tailwind    # Include Tailwind CSS
superimg new my-video --yes         # Skip prompts, use defaults

superimg dev

Start a live preview server with hot reload.

superimg dev my-video

Opens your browser to a local preview. Edit your template, and the video updates instantly.

Options:

superimg dev my-video --port 3000   # Custom port
superimg dev my-video --no-open     # Don't auto-open browser
superimg dev                        # Home mode (lists all templates)

superimg render

Export your template to media.

superimg render my-video.media.ts

Output is colocated with the template: an output/ folder is created next to the .media.ts file. So path/to/my-video.media.ts renders to path/to/output/my-video.mp4.

Options:

# Custom output path
superimg render template.media.ts -o my-video.mp4
superimg render template.media.ts -o ./videos/  # Directory
 
# Quality and format
superimg render template.media.ts --quality high
superimg render template.media.ts --format webm
superimg render template.media.ts --format gif
superimg render template.media.ts --fps 60
 
# Single-frame still capture
superimg render template.media.ts --frame 45 --format png
superimg render template.media.ts --frame 45 --format html  # HTML snapshot
 
# Dimensions (override template config)
superimg render template.media.ts --width 1080 --height 1920
 
# Pass data
superimg render template.media.ts --data '{"title": "Custom Title"}'
superimg render template.media.ts --data products.json -y  # Batch: one file per entry
 
# Render all templates in project
superimg render --all -y

superimg list

Show all templates in your project.

superimg list

Output:

Name          Kind    Config           Path
────────────  ──────  ───────────────  ─────────────────────────
my-video      video   1920x1080 30fps  videos/my-video/my-video.media.ts
og-card       image   1200x630         src/og-card.media.ts

superimg discover

Fast filesystem discovery for build tool integration — no template parsing.

superimg discover --json

superimg validate

Render sample frames and check for errors.

superimg validate my-video.media.ts

superimg init

Scaffold a new SuperImg project.

superimg init my-project
cd my-project

Options:

superimg init my-project --yes      # Skip prompts
superimg init my-project --pm pnpm  # Use pnpm instead of npm

superimg setup

Download required browser binaries (Playwright/Chromium).

superimg setup

Run this once after installing SuperImg, or if rendering fails with browser errors.

superimg skill install

Install the SuperImg AI skill for coding agents (Claude, Cursor, Codex, etc.).

superimg skill install

Render Options Reference

FlagDescriptionDefault
-o, --outputOutput file or directory<template-folder>/output/<name>.mp4
--formatOutput format (mp4, webm, gif, png, webp, jpeg, html)mp4
--frameCapture a single frame (pairs with --format png|webp|jpeg|html)—
--qualityQuality preset (low, medium, high, very-high)medium
--fpsFrames per secondTemplate config
--widthWidth in pixelsTemplate config
--heightHeight in pixelsTemplate config
--dataJSON data or path to .json/.ts/.js data file{}
--presetUse a named output preset from template config—
--presetsRender all presets defined in template—
--debug-htmlSave frame HTML next to the resolved output in .superimg/debug/—

Video Codec Options

For fine-grained control over encoding:

# Video codec
superimg render template.media.ts --video-codec av1
superimg render template.media.ts --video-codec vp9
 
# Bitrate
superimg render template.media.ts --video-bitrate 2000000
 
# Audio (if your template has audio)
superimg render template.media.ts --audio-codec opus
superimg render template.media.ts --audio-bitrate 128000

Output Presets

Define reusable output configurations in your template:

import { define } from "superimg";
 
export default define({
  config: {
    width: 1920,
    height: 1080,
    outputs: {
      "instagram-story": { width: 1080, height: 1920 },
      "youtube-short": { width: 1080, height: 1920, fps: 60 },
      "square": { width: 1080, height: 1080 },
    }
  },
  // ...
})

Then render with:

superimg render template.media.ts --preset instagram-story
superimg render template.media.ts --presets  # Render all presets

File Discovery

SuperImg automatically finds all *.media.ts files anywhere in your project. Output kind (video, image, gif, svg) is read from each template's config at parse time:

project/
├── videos/intro/intro.media.ts      ✓ video (has fps + duration)
├── src/og-card.media.ts             ✓ image (no fps/duration)
├── examples/spinner.media.ts        ✓ gif (--format gif)
└── charts/sine-wave.media.ts        ✓ svg (medium: "svg")

No configuration needed.

Next Steps