CLI¶
The full command tree below is generated from the installed scrolly
CLI, so it can't drift from the code.
scrolly¶
scrolly — compile a JSON5 deck into a self-contained 2D-canvas HTML presentation.
Usage:
scrolly [OPTIONS] COMMAND [ARGS]...
Options:
--version Show the version and exit.
--help-for-ai-tools Print the entire CLI reference (commands, schemas,
error codes) as one markdown document for AI agents.
--help Show this message and exit.
build¶
Build a deck into a self-contained HTML presentation.
Usage:
scrolly build [OPTIONS] DECK_PATH
Options:
--out DIRECTORY Output directory. [required]
--out-file TEXT Name of the output HTML file inside the
output directory. [default: index.html]
--force Overwrite a non-empty output directory.
--no-inline Write assets as separate files instead of
inlining.
--strict Enable additional lint checks (e.g. out-of-
range keyframes).
--simplified-zoom-control Use the legacy single-icon zoom-out control
instead of the default deck mini-map.
--no-compress Disable gzip compression of the output
document and its inlined assets.
--offline Skip the mermaid CDN download and use the
wheel-bundled mermaid for byte-
reproducibility. SCROLLY_OFFLINE=1 in the
environment is equivalent.
--reencode-bitmaps QUALITY|off Re-encode raster images
(jpeg/png/gif/webp/avif) to the smallest of
WebP/AVIF candidates at the given quality,
shipping the original when it wins. Never
enlarges a deck; SVG is never touched. Use
'off' to disable. [default: 95]
--allow-path DIRECTORY Extra directory authored file references may
resolve into; repeatable. By default every
referenced file must live inside the deck
directory.
--help Show this message and exit.
errors¶
Look up registered error codes.
scrolly errors → formatted index of all codes with summaries
scrolly errors → long-form catalog entry for
scrolly errors --list-codes → bare codes, one per line (agent / scripting)
Usage:
scrolly errors [OPTIONS] [CODE]
Options:
--list-codes Print bare codes one per line (no summaries) for scripting
use.
--help Show this message and exit.
expand¶
Show the rendered text of a slide's template instantiations.
Renders each template / template_file element of the slide with
its actual with: values and prints the post-Jinja, pre-validation
text — the debugging surface for rendered-output errors (E803).
Expansion is example-based: it always goes through a concrete
instantiation, never a hypothetical variable set.
Usage:
scrolly expand [OPTIONS] DECK_PATH
Options:
--slide TEXT Slide id whose template instantiations to expand.
[required]
--allow-path DIRECTORY Extra directory authored file references may resolve
into; repeatable.
--help Show this message and exit.
init¶
Scaffold a minimal deck in DIR_PATH.
Usage:
scrolly init [OPTIONS] DIR_PATH
Options:
--help Show this message and exit.
introspect¶
Inspect a resolved deck — JSON-only views for downstream consumers.
Usage:
scrolly introspect [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
assets¶
Asset table — declared assets, per-slide references, byte sizes, mime types.
Walks the resolved slide IRs for ImageElement / ImageSequenceElement
references. Each entry reports absolute path, name, size, mime, exists
flag, and the slides that reference it.
Output format may change before scrolly v1.0 — pin a version when caching the schema.
Usage:
scrolly introspect assets [OPTIONS] DECK_PATH
Options:
--slide TEXT Restrict the asset walk to elements within the named
slide(s). Repeatable.
-o, --output FILE Write JSON to this file instead of stdout.
--help Show this message and exit.
dom¶
Rendered HTML + scoped CSS per element, sans deck-level chrome.
Answers "what does my config actually become" by running each slide's element renderers and surfacing the per-element pieces — HTML fragment and CSS rules — directly. No canvas runtime, no scrollbar, no edge geometry, no inter-slide chrome.
Output format may change before scrolly v1.0 — pin a version when caching the schema.
Usage:
scrolly introspect dom [OPTIONS] DECK_PATH
Options:
--slide TEXT Restrict output to the named slide id(s). Repeatable.
Default = all slides — but unfiltered output can be
hundreds of KB; the filter is almost mandatory in
practice.
-o, --output FILE Write JSON to this file instead of stdout.
--help Show this message and exit.
elements¶
Fully-resolved element tree per slide.
Defaults are filled in, *_file fields are inlined, asset paths
are absolute. Animated properties surface as their keyframe lists;
static properties surface as their values.
Output format may change before scrolly v1.0 — pin a version when caching the schema.
Usage:
scrolly introspect elements [OPTIONS] DECK_PATH
Options:
--slide TEXT Restrict output to the named slide id(s). Repeatable.
Default = all slides.
-o, --output FILE Write JSON to this file instead of stdout.
--help Show this message and exit.
slides¶
Deck topology — slides, edges, groups, geometry.
Returns a deck-wide overview: every slide with its grid coord, title, resolved scroll_range, element + snap counts; every edge with fully-specified sides; every group with members and color.
No --slide filter — the value of this view is the relationships
between slides, which filtering would destroy.
Output format may change before scrolly v1.0 — pin a version when caching the schema.
Usage:
scrolly introspect slides [OPTIONS] DECK_PATH
Options:
-o, --output FILE Write JSON to this file instead of stdout.
--help Show this message and exit.
snaps¶
Per-slide snap positions: author-supplied + element-derived (image_sequence hold-centers).
Author entries come from each slide's snap_positions field;
derived entries come from ImageSequenceElement hold-centers
(one per frame). The merged list is the deduplicated + sorted
union — what the canvas runtime actually uses.
Output format may change before scrolly v1.0 — pin a version when caching the schema.
Usage:
scrolly introspect snaps [OPTIONS] DECK_PATH
Options:
--slide TEXT Restrict output to the named slide id(s). Repeatable.
Default = all slides.
-o, --output FILE Write JSON to this file instead of stdout.
--help Show this message and exit.
snapshot¶
Resolve every element's substrate properties at the given scroll position(s).
For each --scroll N the seven substrate properties — position,
width, height, anchor, opacity, scale, angle —
are interpolated to numeric values per element. A visible flag
(opacity > 0) is derived alongside. Type-specific content
(image path, markdown text, iframe HTML) is omitted since it
doesn't change with scroll.
Scroll positions are validated against the slide's scroll_range:
negative scrolls or scrolls beyond a numeric scroll_range reject
the whole invocation (those scrolls are never physically reachable).
For scroll_range: "auto" slides only the lower bound is enforced
build-side.
Output format may change before scrolly v1.0 — pin a version when caching the schema.
Usage:
scrolly introspect snapshot [OPTIONS] DECK_PATH
Options:
--slide TEXT Slide id to snapshot. Mandatory and single-valued —
scroll positions are slide-local. [required]
--scroll FLOAT Scroll position(s) to snapshot at. Mandatory; repeat for
multiple scrolls. [required]
-o, --output FILE Write JSON to this file instead of stdout.
--help Show this message and exit.
timeline¶
Per-element scroll timeline: animated keyframes + visibility intervals.
animated_properties lists only the substrate properties that are
actually animated (statics are omitted to avoid redundancy with
introspect elements). visibility_intervals reports scroll
ranges where opacity > 0 — half-open at the boundaries; the
upper bound is null for scroll_range: "auto" slides where
the browser determines the actual extent at runtime.
Output format may change before scrolly v1.0 — pin a version when caching the schema.
Usage:
scrolly introspect timeline [OPTIONS] DECK_PATH
Options:
--slide TEXT Restrict output to the named slide id(s). Repeatable.
Default = all slides.
-o, --output FILE Write JSON to this file instead of stdout.
--help Show this message and exit.
schema¶
Show source-file and slide-element schemas.
scrolly schema → combined index (file + element schemas)
scrolly schema file [
Append --list-types to either subcommand for bare names (agent / scripting).
Shows static type definitions; use scrolly introspect for a resolved deck.
Usage:
scrolly schema [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
element¶
Slide-element schemas (markdown, image, …).
scrolly schema element → formatted index of element types
scrolly schema element
Usage:
scrolly schema element [OPTIONS] [TYPE_NAME]
Options:
--list-types Print bare element keys one per line (no descriptions) for
scripting use.
--help Show this message and exit.
file¶
Source-file schemas (deck, slide).
scrolly schema file → formatted index of file types
scrolly schema file
Usage:
scrolly schema file [OPTIONS] [TYPE_NAME]
Options:
--list-types Print bare file-type names one per line (no descriptions) for
scripting use.
--help Show this message and exit.
template¶
Parameter contract of a template file (front-matter params).
scrolly schema template
Lists each declared param's type, default, required flag, and
description — what an instantiation's with: block must satisfy.
Usage:
scrolly schema template [OPTIONS] TEMPLATE_PATH
Options:
--help Show this message and exit.
validate¶
Validate a deck and all its slide sources without building.
Usage:
scrolly validate [OPTIONS] DECK_PATH
Options:
--strict Enable additional lint checks (e.g. out-of-range
keyframes).
--json Emit machine-readable JSON instead of text: {"ok":
bool, "errors": [...]}.
--allow-path DIRECTORY Extra directory authored file references may resolve
into; repeatable. By default every referenced file
must live inside the deck directory.
--help Show this message and exit.