@bendyline/squisq-cli

Command-line tool and programmatic API for converting Squisq documents between DOCX, PPTX, PDF, XLSX, CSV, HTML, EPUB, Markdown, and container ZIP — and rendering them to MP4 video or animated GIF. Reads Markdown, binary documents (.docx/.pptx/.pdf/.xlsx/.csv/.html), ZIP/.dbk containers, folders, or pre-built Doc JSON as input.

Part of the Squisq monorepo.

Install

npm install -g @bendyline/squisq-cli

For squisq video (and convert to mp4 or gif) you also need:

• ffmpeg — resolved from the SQUISQ_FFMPEG env var, then your PATH (brew install ffmpeg / apt install ffmpeg / winget install ffmpeg), then an optionally-installed ffmpeg-static package.
• A Playwright-managed Chromium for headless frame capture (e.g. npx playwright install chromium)

Run squisq doctor to check the video toolchain. Document conversion to non-video formats has no native requirements.

Commands

squisq convert <input>

Convert a document to one or more formats. Input can be Markdown or a binary document (.docx, .pptx, .pdf, .xlsx, .csv, .html), a .zip/.dbk container, or a folder. Conversion goes through Squisq's MarkdownDocument pivot model and preserves most of the flavor of the document (structure, formatting, tables, images) — it is not a lossless round-trip.

squisq convert input.md -o report.docx           # single file; format inferred from extension
squisq convert report.docx -o report.md           # binary input → markdown
squisq convert input.md --formats pptx             # single format to the default output dir
squisq convert input.md --formats docx,pptx,pdf    # multiple formats
squisq convert project.dbk --output-dir ./out --formats html,docx
squisq convert input.md --theme cinematic --transform magazine --formats pptx

v1.5 breaking flag change: -o is now a single-file destination (format inferred from the extension). The old -o output-directory behavior is now -d, --output-dir. A bare convert <input> with no -o/--formats writes a default set that deliberately excludes md/xlsx/csv/mp4/gif.

Notes:

• Existing files are never overwritten by default. A bare convert report.md writes several files next to the input; if any already exists the run refuses up front (before converting anything) and exits 1. Pass --overwrite to replace them. The flag is --overwrite, not -f, because -f is --formats. There is no prompt — this stays scriptable.
• An unknown --formats id is a hard error. -f docx,pfd fails with Unknown format: "pfd" (did you mean "pdf"?) and produces nothing, rather than warning and exiting 0 with the PDF silently missing.
• html produces a single self-contained file with the standalone player inlined (static mode); htmlzip produces a <name>.html.zip archive with external assets and optional audio.
• epub embeds images from the input container and, when the doc has narration segments, generates EPUB 3 Media Overlays.
• xlsx export is tables-only; csv export emits the first table; mp4 and gif require the render toolchain (see Install).
• dbk re-serializes the input container as a ZIP.

squisq video <input> [output]

Render a document to MP4 or animated GIF. Playwright captures deterministic frames from a headless player page; native ffmpeg encodes H.264 + AAC for MP4 or a generated global palette for GIF. Documents with Mermaid fences automatically use the full standalone player so diagrams are captured; other documents keep the smaller light player. GIF has no audio track.

squisq video input.md output.mp4
squisq video input.md output.gif
squisq video input.md --format gif --no-animations
squisq video project.dbk --quality high --fps 30
squisq video ./my-folder --orientation portrait --captions social
squisq video input.md -t documentary --transform magazine --cover-preroll 1.5
squisq video doc.json -o out.mp4

Notes:

• Dimensions must be even. --width 851 is rejected immediately — before the document is read or a browser launches — with Video width must be an even number of pixels (got 851) … Use 850 or 852. Odd values are rejected rather than rounded, so a render never silently ships at a size you did not ask for. The rule is the same for MP4 and GIF, and matches browser export.
• An existing output file is never overwritten by default. The check runs before rendering, so a colliding path costs you a second rather than a full capture. Pass --overwrite to replace.
• FFmpeg failures report the one relevant line (e.g. [libx264] width not divisible by 2 (851x480) (exit code 1)) rather than dumping the whole command line and stderr buffer.
• MP4 frames stream to ffmpeg as they are captured. Memory stays flat for a story of any length; --frame-transport memory restores the old retain-then-encode path, which is bounded to a few seconds of 1080p photo slides. --frames-dir keeps every still (plus a manifest.json naming the doc, size, rate, captions and animation settings), and --resume skips re-capturing stills that an identical render already spooled there.
• Portrait and custom sizes are composed natively. The render page pins the player's viewport to the export size; a player bundle that ignores it fails the run before capture instead of producing a letterboxed landscape layout.

squisq image <input> [output]

Render a document's Dashboard rendition — every block arranged on one canvas — to a PNG image. Needs Playwright Chromium only (no ffmpeg; this is a single-frame capture, not a video encode). The layout comes from the doc's squisq-dashboard-layout frontmatter (or --layout), defaulting to the auto-pick that chooses the smallest built-in layout fitting the block count; the document-title band renders by default and --no-title hides it. --style picks the cell dressing (basic, card, panel, accent — all theme-derived), defaulting to the doc's squisq-dashboard-style.

squisq image input.md output.png
squisq image input.md --resolution 4k
squisq image input.md --resolution square --layout grid-2x2
squisq image input.md --style card
squisq image input.md --width 1280 --height 720 --no-title
squisq image input.md -t documentary --transform magazine

The same export is available through the registry as squisq convert <input> -f png.

squisq doctor

Preflight the rendering toolchain: reports the resolved ffmpeg path, version, and which source it came from (SQUISQ_FFMPEG env / PATH / ffmpeg-static) with an install hint when missing, attempts a headless Chromium launch, reports the Node version, and summarizes per-feature readiness (video/GIF need ffmpeg + Chromium; the dashboard PNG image needs Chromium only).

squisq doctor

squisq validate <input>

Structurally validate a .md file, .zip/.dbk container, or folder. Reports unknown templates (with did-you-mean), unparsed {[…]} annotations, malformed heading attributes, unresolved connections, duplicate ids, bad data fences, and missing asset references — with line numbers.

squisq validate input.md
squisq validate project.dbk --json
squisq validate ./my-folder --strict

Diagnostics are reported at three severities — error, warning, and info (info is counted and shown separately). Exit codes depend on errors only: 0 clean, warnings-only, or info-only; 1 errors (or any warning with --strict); 2 input unreadable.

squisq transform <input>

The condense operation compacts table padding and decorative dividers while retaining table data, alignment, code, citations, and attribution. It verifies structural equivalence before returning. When combining operations, put condense after cleanup so serialization does not reintroduce padding.

Apply one-time markdown source transforms to a .md file, in the order given: unwrap (remove forced line wrapping so each paragraph is one line — hard breaks kept), wrap (hard-wrap paragraph prose at a column width on word boundaries — code, tables, and headings untouched), and cleanup (canonical house-style normalization: bullets, emphasis, headings, table padding, spacing; annotations and frontmatter preserved). Not to be confused with the --transform <style> slideshow-style flag on convert/video — this command rewrites the markdown text itself.

The transformed markdown goes to stdout by default (status messages go to stderr, so it pipes cleanly).

squisq transform doc.md --ops unwrap
squisq transform doc.md --ops unwrap,cleanup > cleaned.md
squisq transform doc.md --ops wrap --width 100 --in-place
squisq transform doc.md --ops cleanup -o cleaned.md
squisq transform doc.md --ops condense -o compact.md

Transforms run in strict mode: each one reparses its output and structurally compares it against the input document; if equivalence cannot be proven, the command exits 1 without emitting anything. Exit codes: 0 success, 1 transform/output failure, 2 input unreadable.

Input Formats

All commands accept:

Programmatic API

Import @bendyline/squisq-cli/api to use the same pipeline as a library from Node.js — no shell-out required. Like the CLI, renderDocToMp4 and renderDocToGif require ffmpeg and a Playwright-managed Chromium.

convert()

A pre-bound wrapper over @bendyline/squisq-formats' convert() that injects the CLI's format registry (every built-in exporter plus the CLI-only mp4 and gif formats) and a default resolvePlayerScript (so HTML/player-embedding exports work out of the box). Both are overridable via options. createCliRegistry() returns that same registry for direct use.

import { convert, createCliRegistry, ConversionError } from '@bendyline/squisq-cli/api';

const result = await convert({ kind: 'markdown', markdown: '# Hello' }, 'docx');
// result.bytes (Uint8Array), result.mimeType, result.suggestedFilename, result.warnings

ConversionError (with a stable code) and the ConvertSource / ConvertOptions / ConversionResult / FormatRegistry types are re-exported for convenience.

renderDocToMp4

import { renderDocToMp4, readInput } from '@bendyline/squisq-cli/api';

// Load a document from disk (.md, .zip/.dbk, folder, or Doc .json)
const input = await readInput('./my-article.md');

// `doc` is always normalized and ready to render. `markdownDoc` is present
// only when the source was markdown-shaped; `sourceFormat` identifies the input.
const { doc, container, markdownDoc, sourceFormat } = input;

// Render to MP4
const result = await renderDocToMp4(doc, container, {
  outputPath: './output.mp4',
  fps: 30, // default 30
  quality: 'high', // 'draft' | 'normal' | 'high' (default 'normal')
  orientation: 'landscape', // 'landscape' | 'portrait' (default 'landscape')
  captionStyle: 'social', // 'off' | 'standard' | 'social' (default 'off')
  animationsEnabled: false, // static slide changes; media/timing remain active
  coverPreRoll: 2, // seconds of cover-slide pre-roll (default 0)
  frameTransport: 'pipe', // 'pipe' (default; streams stills to ffmpeg) | 'memory'
  captureFormat: 'png', // 'png' | 'jpeg' (default: png for high quality, jpeg otherwise)
  framesDir: './frames', // optional: keep every still + manifest; with resume: true, reuse them
  onFrame: ({ index, totalFrames, captureMs, reused }) => {}, // per-frame throughput hook
  onProgress: (phase, pct) => console.log(`${phase}: ${pct}%`),
});
// result: { duration, frameCount, outputPath, reusedFrameCount?, framesDir? }

console.log(`Rendered ${result.frameCount} frames (${result.duration}s) → ${result.outputPath}`);

The container's audio segments become the MP4's audio track; timed media clips and block videos found in the doc are embedded and mixed at their scheduled positions.

The capture page loads nothing from the network, so a theme font the rendering machine lacks (any Google Fonts stack, such as warm-earth's DM Sans body) renders in a fallback face. Pass the font files as fonts, one entry per file; every renderer here (MP4, GIF, cover and dashboard PNG) accepts them:

const fonts: RenderFontFace[] = [
  { family: 'DM Sans', data: await readFile('DMSans-Variable.woff2'), weight: '100 1000' },
  {
    family: 'DM Sans',
    data: await readFile('DMSans-VariableItalic.woff2'),
    weight: '100 1000',
    style: 'italic',
  },
];
await renderDocToMp4(doc, container, { outputPath: './output.mp4', fonts });

format defaults to 'woff2' (also 'woff', 'truetype', 'opentype'), and unicodeRange takes a CSS unicode-range for a file holding one subset.

renderDocToGif

import { renderDocToGif } from '@bendyline/squisq-cli/api';

const result = await renderDocToGif(doc, input.container, {
  outputPath: './output.gif',
  fps: 10,
  captionStyle: 'off', // override the default 'standard' captions
  animationsEnabled: false,
  maxColors: 256,
  loop: 0,
});

GIF defaults to 960×540 landscape (540×960 portrait), 10 fps, standard captions, an infinite loop, and disabled slide animations/transitions. Set captionStyle: 'off' to omit captions. Embedded video still advances, but all audio is omitted and reported through result.warnings.

renderDocToDashboardPng

import { renderDocToDashboardPng } from '@bendyline/squisq-cli/api';

const result = await renderDocToDashboardPng(doc, input.container, {
  outputPath: './dashboard.png',
  resolution: 'square', // or width/height for custom pixels
  layout: 'grid-2x2', // 'auto' (default) picks by block count
  style: 'card', // 'basic' (default) | 'card' | 'panel' | 'accent'
  title: true,
});
// result: { bytes: Uint8Array, width, height, outputPath? }

Renders the Dashboard rendition to a single PNG. Needs Playwright Chromium only — no ffmpeg. resolution names a preset from DASHBOARD_RESOLUTIONS (default fhd, 1920×1080); explicit width/height (both together) replace it. Apply a theme upstream ({ ...doc, themeId }), the same convention the video renderers use.

Native frame encoding

For callers that already have PNG frames and do not need Playwright capture, the API exposes the native FFmpeg layer directly:

import { framesToGifNativeBytes, framesToMp4NativeBytes } from '@bendyline/squisq-cli/api';

const mp4 = await framesToMp4NativeBytes('/usr/bin/ffmpeg', pngFrames, audioBytes, {
  fps: 30,
  quality: 'high',
});

const gif = await framesToGifNativeBytes('/usr/bin/ffmpeg', pngFrames, {
  fps: 10,
  width: 960,
  height: 540,
});

The path variants write to a caller-supplied output; each Bytes variant returns a Uint8Array. MP4 pads short audio with silence so narration cannot truncate the timeline. GIF uses a compression-friendly diff palette and changed-rectangle application.

extractThumbnails

Extract JPEG thumbnails from the first frame of a rendered video:

import { extractThumbnails } from '@bendyline/squisq-cli/api';

await extractThumbnails({
  videoPath: './output.mp4',
  outputDir: './thumbs',
  slug: 'my-article', // filenames: {slug}-{width}x{height}.jpg
  sizes: [
    { name: 'og', width: 1200, height: 630, filter: 'scale=1200:630' },
    { name: 'thumb', width: 480, height: 270, filter: 'scale=480:270' },
  ],
  force: false, // overwrite existing files (default false)
});

Other exports

• readInput(inputPath) → { doc: Doc, container: ContentContainer, markdownDoc?: MarkdownDocument, sourceFormat: FormatId }
• MemoryContentContainer (re-export from @bendyline/squisq/storage)
• VideoQuality, VideoOrientation types (re-exports from @bendyline/squisq-video)
• DASHBOARD_RESOLUTIONS, DEFAULT_DASHBOARD_RESOLUTION, resolveDashboardDimensions, validateDashboardImageDimensions (re-exports from @bendyline/squisq-video)

See the full API Reference for all types and options.

Related Packages

License

MIT