@bendyline/docblocks-cli

The DocBlocks command-line surface for document build and preview, linked-Squisq format conversion, MP4 rendering, document parsing, workspace catalog refresh, and a local MCP server for agents.

CLI and MCP overview

Installation

Node.js 24.18.0+ or 26+ is required.

npm install -g @bendyline/docblocks-cli
docblocks --help

Documentation

• Authoritative CLI reference
• MCP architecture and protocol guide

Those guides describe current input support, linked Squisq ownership, format directions, overwrite behavior, MCP authority, artifact lifecycle, and assurance.

Commands

| Command | Purpose | | ----------------------------------- | --------------------------------------------------------------- | | docblocks build | Recursively build Markdown into standalone HTML. | | docblocks serve | Run a constrained local preview server. | | docblocks convert <input> | Convert through the linked Squisq registry. | | docblocks video <input> [output] | Render a configurable MP4. | | docblocks mcp | Start the artifact-first MCP server over local stdio. | | docblocks themes | List linked Squisq theme IDs. | | docblocks transforms | List linked Squisq transform IDs. | | docblocks parse <input> | Parse UTF-8 Markdown into Squisq Markdown AST JSON. | | docblocks workspace refresh [dir] | Refresh catalog outputs enabled in .docblocks/workspace.json. |

Use docblocks help <command> for the installed option summary.

Examples

# Build and preview Markdown
docblocks build --input ./docs --output ./dist
docblocks serve --dir ./docs

# The no-flag conversion set is exactly DOCX, PPTX, PDF, HTML, and DBK
docblocks convert story.md

# Select any export-capable linked-registry formats
docblocks convert report.docx --formats md,pdf,pptx --output-dir ./exports

# Render MP4 with explicit media controls
docblocks video story.md --quality high --orientation portrait

# Render the Dashboard rendition to a square image with accent cards
docblocks convert report.md --formats png --image-resolution square --image-style accent

# Regenerate the catalog.json / index.html a workspace opts into
docblocks workspace refresh ./docs --dry-run
docblocks workspace refresh ./docs

# Discover authoring vocabulary from linked Squisq
docblocks themes
docblocks transforms

# Start MCP with no filesystem authority
docblocks mcp

# Grant independent roots when an agent needs files or durable output
docblocks mcp --allow-read ./documents --allow-write ./exports

For durable output, call list_roots before drafting. If no root is write-enabled, restart the server with --allow-write; do not bypass MCP with the direct convert command. Plain text or ordinary Markdown can be passed directly to convert_document without a preflight; compatible templates are chosen automatically, and explicit Squisq annotations remain optional overrides. For PPTX, a level-one heading creates each deliberate slide boundary by itself; do not add --- between slide headings unless a visible horizontal rule is intended. get_authoring_context is optional discovery for exact annotation examples, safe defaults, and semantically described theme/Summarize choices. MCP guidance tells agents to infer and choose a style from the brief rather than presenting raw IDs, asking one compact high-level question only when the choice is materially ambiguous. The complete catalog remains available at docblocks://authoring-guide.

convert and video accept Markdown, Squisq JSON Doc, DBK/ZIP, folders, and import-capable linked-registry formats. video also renders Dynamic slides from current text and saved design preferences against narration sidecars; stale narration or missing timings fail export. Legacy saved presentation plans remain readable. build/serve standalone HTML includes Copy controls for ordinary fenced code blocks; Mermaid fences remain diagrams. Without --theme, build/serve apply documents.defaultTheme from .docblocks/workspace.json to documents whose frontmatter names no theme; --ignore-workspace-settings opts out. workspace refresh writes only outputs the settings enable, replaces only files carrying the DocBlocks catalog marker, writes only when bytes differ, and exits 1 when a hand-written file blocks an output. build replaces generated HTML files; convert and video refuse existing destinations unless --allow-overwrite is passed. Multi-target conversion stages the complete batch and rolls back replacements if publication fails. Build traversal, input bytes, and output bytes are bounded, as are parse input and JSON output. MCP conversions instead return immutable session artifacts; only explicit save_artifact materializes one, using no-replace or hash-conditional replacement semantics.

The package root is a side-effect-free programmatic API for runBuild, runConvert, runVideo, runParse, and runWorkspaceRefresh. Importing it never starts Commander; the executable is the separate docblocks bin entry.

The live linked registry currently covers Markdown, DOCX, PDF, PPTX, XLSX, CSV, HTML, HTML ZIP, EPUB, DBK, MP4, GIF, and PNG. Direction varies by format, so use the CLI reference or MCP list_formats rather than assuming every format imports.

MP4/GIF rendering requires Chromium and FFmpeg. Install Chromium with npx playwright install chromium; Squisq resolves FFmpeg from SQUISQ_FFMPEG, PATH, or ffmpeg-static, in that order. PNG renders the document's Dashboard rendition to a single image and needs Chromium only.