CLI reference

molen is the one entry point to every engine operation. This page is generated from the same OPS_CATALOG contract that molen describe prints and the MCP server serves, so it can never drift from the shipped commands.

Running the CLI

Inside a project that installs @bendyline/molen-tooling (every molen new project does), run npx molen <cmd>; the usage lines below drop the npx. To create that project, name the scoped package — the unscoped molen on npm is unrelated.

npx @bendyline/molen-tooling new my-experience   # scaffold a runnable project
npx molen validate scene.json                    # cheap — do it constantly
npx molen sim run scene.json --ticks 30 --assert checks.json --hash
npx molen shot scene.json --ticks 30 --camera 0,6,16 --look 0,0,0 --out shot.png

47 commands, in the order you tend to meet them. Each entry shows the usage line (where the CLI flag spellings live) and a table of the operation's input fields — the same fields the MCP tool and the @bendyline/molen-tooling function take.

Validate and discover

Cheap, fast checks you run constantly. validate gives pinpointed, fixable errors; the rest let an agent learn the surface without reading source.

molen validate

Validate a JSON asset against its schema (kind auto-detected from the envelope).

molen validate <path> [--kind <kind>] [--project <project.json>] [--verify-files]

Parameter	Type	Required	Description
path	string	no	Path to a JSON document (or pass inline over MCP).
inline	object	no	Validate this inline document instead of reading a path (MCP).
kind	string	no	Force a schema kind; otherwise detected from "format".
projectPath	string	no	Project manifest for scene type references (default: discovered from the scene path).
verifyFiles	boolean	no	For terrain-package manifests, stream-check file containment, size, and SHA-256.
Also available over MCP as validate_asset.

molen schema list

List all registered asset schema kinds.

molen schema list

No parameters. Also available over MCP as list_schemas.

molen schema get

Get a schema kind: JSON Schema + examples + docs reference.

molen schema get <kind>

Parameter	Type	Required	Description
kind	string	yes	Schema kind, e.g. scene, command, assert.
Also available over MCP as get_schema.

molen components

List the known component vocabulary (name, description, owning layer).

molen components [--project <project.json>] [--scene <scene.json>]

Parameter	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
scenePath	string	no	A scene manifest whose custom components extend the vocabulary.
Also available over MCP as list_components.

molen component

Get one component schema + examples.

molen component <name> [--project <project.json>] [--scene <scene.json>]

Parameter	Type	Required	Description
name	string	yes	Component name, e.g. transform, collider.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
scenePath	string	no	A scene manifest whose custom components extend the vocabulary.
Also available over MCP as get_component.

molen describe

Machine-readable contracts for every molen operation (CLI + MCP).

molen describe [op]

Parameter	Type	Required	Description
name	string	no	Op/tool name or CLI fragment; omit for the full catalog.
Also available over MCP as describe_op.

molen docs search

Lexical search over the shipped engine docs (docs-src bundle).

molen docs search <query> [-k N] [--design]

Parameter	Type	Required	Description
query	string	yes	Search terms.
k	int>0	no	Max results (default 5).
includeDesign	boolean	no	Also search the docs/ design plan (tagged).
Also available over MCP as search_docs.

Simulate and verify

The headless inner loop. Every run is deterministic, so a state hash is a meaningful regression signal and a replay mismatch localizes the diverging tick.

molen sim run

Run a scene headlessly for N ticks; returns tick, state hash, events, assertions.

molen sim run <scene> --ticks <N> [--commands <f>] [--assert <f>] [--setup <m>] [--project <project.json>] [--hash]

Parameter	Type	Required	Description
scenePath	string	yes	Path to a scene manifest JSON.
ticks	int>0	yes	Number of ticks to simulate.
commandsPath	string	no	JSON array (or {commands:[...]}) of command envelopes.
assertPath	string	no	A molen/assert@1 document to evaluate after the run.
setupModule	string	no	ESM module exporting setup(world, manifest).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
Also available over MCP as run_simulation.

molen sim watch

Rerun the simulation + assertions on every input-file change, reporting what moved.

molen sim watch <scene> --ticks <N> [--commands f] [--assert f] [--setup m] [--project <project.json>]

Parameter	Type	Required	Description
scenePath	string	yes	Scene manifest path.
ticks	int>0	yes	Ticks per run.
commandsPath	string	no	JSON array (or {commands:[...]}) of command envelopes.
assertPath	string	no	A molen/assert@1 document evaluated after every run.
setupModule	string	no	ESM module exporting setup(world, manifest).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
CLI only — not exposed over MCP.

molen replay

Replay a fixture and compare the state hash; localizes divergence on mismatch.

molen replay <fixture> [--setup <m>] [--project <project.json>] [--record]

Parameter	Type	Required	Description
path	string	yes	Path to a *.replay.json fixture.
setupModule	string	no	ESM module exporting setup(world, manifest).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
record	boolean	no	Regenerate expected hashes from the current build.
Also available over MCP as run_replay.

molen diff

Component-level diff between two keyframe JSON files.

molen diff <a.keyframe.json> <b.keyframe.json>

Parameter	Type	Required	Description
a	string	yes	Before keyframe path.
b	string	yes	After keyframe path.
Also available over MCP as diff_snapshots.

molen types test

Smoke-test every registry type standalone: resolved shape validates, spawns, and survives N simulated ticks.

molen types test [ids…] [--ticks N]

Parameter	Type	Required	Description
ticks	int>0	no	Ticks to simulate each type (default 30).
only	string[]	no	Restrict to these type ids.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
Also available over MCP as test_types.

Render and play

Turn a scene into pixels without a browser — or drive a real built app with scripted input and collect screenshots and diagnostics.

molen shot

Render one deterministic headless PNG of a scene; returns render stats.

molen shot <scene> --out <png> [--ticks N] [--setup <m>] [--project <project.json>] [--camera x,y,z] [--look x,y,z] [--size WxH] [--clear-color <css>] [--terrain d.json --heightmap h.png] [--variant ktx2]

Parameter	Type	Required	Description
scenePath	string	yes	Path to a scene manifest JSON.
outPath	string	yes	Output PNG path.
ticks	int>=0	no	Tick to simulate to before snapshotting (default 0).
setupModule	string	no	ESM module exporting setup(world, manifest).
camera	{position,lookAt}	no	Camera position and optional look-at target.
size	[w,h]	no	Image size (default 1280x720).
clearColor	string	no	Background colour (CSS/hex) instead of the scene default.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
assetVariant	string	no	Render packed asset variants (e.g. "ktx2" from asset pack) where present.
terrain	{descriptorPath,heightmapPath}	no	Render a terrain descriptor + heightmap.
Also available over MCP as screenshot_scene.

molen frames

Render a tick range to a PNG sequence, optionally following a camera track.

molen frames <scene> --out-dir <d> --from <N> --to <M> [--step S] [--track f] [--setup m] [--project <project.json>] [--camera x,y,z] [--look x,y,z] [--size WxH]

Parameter	Type	Required	Description
scenePath	string	yes	Scene manifest path.
outDir	string	yes	Output directory.
from	int>=0	yes	First tick.
to	int>=0	yes	Last tick.
step	int>0	no	Tick stride between frames (default 1).
setupModule	string	no	ESM module exporting setup(world, manifest).
trackPath	string	no	Camera track JSON followed across the range.
camera	{position,lookAt}	no	Fixed camera when no track is given.
size	[w,h]	no	Image size (default 1280x720).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
Also available over MCP as export_frames.

molen drive

PLAY a scene deterministically: commands in at chosen ticks, screenshot frames out — a repeatable scenario the agent can look at.

molen drive <scene|name> --actions <actions.json> --out-dir <d> [--setup m] [--until N] [--assert f] [--project <project.json>]

Parameter	Type	Required	Description
scenePath	string	yes	Scene file path or project scene name.
actions	[{at, command?, screenshot?, camera?}]	yes	Tick-ordered actions: submit a command and/or capture a named frame.
until	int>=0	no	Step to this tick after the last action.
assertPath	string	no	molen/assert@1 doc evaluated at the end.
setupModule	string	no	ESM module exporting setup(world, manifest).
size	[w,h]	no	Frame size (default 1280x720).
outDir	string	no	Output directory for the frames (MCP returns them as images).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
Also available over MCP as drive_scene.

molen play

PLAY a built browser experience: timed inputs in, screenshots/probes/diagnostics out.

molen play <built-app-dir> --scenario <experience-play.json> --out-dir <d> [--headed]

Parameter	Type	Required	Description
appDir	string	yes	Built browser app directory containing index.html.
scenario	molen/experience-play@1	yes	Declarative waits, keyboard input, drags, UI actions, probes, and screenshots.
outDir	string	no	Output directory for frames and experience-run.json (MCP uses a temp dir).
Also available over MCP as play_experience.

molen asset shot

Render an imported asset from N turntable angles (framed from its sidecar bounds).

molen asset shot <asset-id|sidecar> --out-dir <d> [--angles N] [--clip name --time s] [--variant ktx2]

Parameter	Type	Required	Description
ref	string	yes	Project asset id or sidecar path.
angles	int>0	no	Turntable angle count (default 4).
size	[w,h]	no	Frame size (default 1280x720).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
clip	string	no	Pose this animation clip.
clipTime	number>=0	no	Clip time in seconds (default 0).
assetVariant	string	no	Render this packed variant (e.g. "ktx2") instead of the canonical GLB.
Also available over MCP as screenshot_asset.

Projects and types

Scaffold an experience (the starter, or a copy of a shipped sample) and manage the namespaced entity type registry.

molen new

Scaffold a new experience (scene + scripts + commands + checks + AGENTS.md) ready for the loop, or a standalone copy of a shipped sample with --template.

molen new <name> [--template <id>] [--dir <path>] [--force]

Parameter	Type	Required	Description
name	string	yes	Experience name (also the output folder name).
template	string	no	Copy this sample instead of the built-in starter (list_templates / molen templates lists the ids).
dir	string	no	Parent directory (default: cwd).
force	boolean	no	Replace existing scaffold-owned files (default false).
Also available over MCP as new_experience.

molen templates

List the sample templates new_experience can copy (id + one-line description); each scaffolds as a standalone npm project.

molen templates [--json]

No parameters. Also available over MCP as list_templates.

molen project info

Show the surrounding project.json: scenes, types, assets, reservations.

molen project info [--project <path>]

Parameter	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
Also available over MCP as get_project.

molen types list

List the entity types registered in the project type registry.

molen types list [--project <path>]

Parameter	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
Also available over MCP as list_types.

molen types check

Validate the type registry: duplicates, cycles, namespace ownership, asset refs, codegen staleness.

molen types check [--project <path>]

Parameter	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
Also available over MCP as check_types.

molen types reserve

Reserve a type/asset id namespace for an owner (multi-agent vocabulary partitioning).

molen types reserve <namespace> --owner <owner> [--note <s>]

Parameter	Type	Required	Description
namespace	string	yes	Dotted namespace, e.g. "train".
owner	string	yes	Owner identity, e.g. "agent:layout".
note	string	no	Free-form note recorded with the reservation.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
Also available over MCP as reserve_type.

molen types gen

Generate (or verify) the typed component/type-id module plus the ambient types beside each scripts directory.

molen types gen [--check] [--out <path>]

Parameter	Type	Required	Description
check	boolean	no	Compare only; fail when a committed artifact is stale.
out	string	no	Output path override (default: project codegen.out).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
Also available over MCP as generate_types.

Assets

Import glTF/GLB, inspect what was imported, and stage runtime bundles for the browser.

molen asset import

Import a glTF/GLB: normalize, extract bounds + collision (hulls/trimesh), write the asset sidecar, register in project.json.

molen asset import <file.glb> [--id <asset-id>] [--trimesh] [--no-optimize] [--out-dir <d>] [--asset-dir <d>] [--project <project.json>] [--force]

Parameter	Type	Required	Description
path	string	yes	Source .glb/.gltf file.
id	string	no	Asset id (default: slugged filename; dotted ids join a namespace).
trimesh	boolean	no	Also extract a whole-asset collision trimesh (collision.bin).
optimize	boolean	no	Normalize pass dedup/prune/weld/quantize (default true).
outDir	string	no	Assets root override; retains root/id layout. Mutually exclusive with assetDir.
assetDir	string	no	Exact bundle directory, relative to cwd. Mutually exclusive with outDir. Omit both to preserve an existing project asset directory.
projectPath	string	no	project.json to register into. Required when the source file sits in a different project than the cwd.
cwd	string	no	Directory to discover the project from (default: process.cwd()).
force	boolean	no	Replace an existing asset directory (default false).
Also available over MCP as import_asset.

molen asset inspect

Read + validate an asset sidecar (by path or project asset id); --verify re-hashes files.

molen asset inspect <sidecar.json | asset-id> [--verify]

Parameter	Type	Required	Description
ref	string	yes	Sidecar path or registered asset id.
verify	boolean	no	Re-hash model.glb / collision.bin against the sidecar.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
Also available over MCP as inspect_asset.

molen asset list

List the assets registered in the surrounding project.

molen asset list [--project <path>]

Parameter	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
Also available over MCP as list_assets.

molen asset pack

Derive a RUNTIME GLB variant: textures re-encoded as KTX2 (Basis) with mipmaps, power-of-two sized, so the GPU gets ASTC/BC7 instead of RGBA8 (4-8x less texture memory). Recorded as files.variants.<variant>.

molen asset pack <asset-id|sidecar> | --all [--variant ktx2] [--mode auto|etc1s|uastc] [--max-size N] [--no-pot] [--etc1s-quality N] [--uastc-quality N]

Parameter	Type	Required	Description
ref	string	no	Project asset id or sidecar path (or pass all: true).
all	boolean	no	Pack every asset registered in the project.
variant	string	no	Variant name / file suffix (default "ktx2").
mode	`auto	etc1s	uastc`
maxSize	int>=4	no	Longest texture side after resizing (default 2048).
powerOfTwo	boolean	no	Snap sides to a power of two (default true).
etc1sQuality	int 1..255	no	ETC1S quality (default 128).
uastcQuality	int 0..4	no	UASTC pack quality (default 2).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
Also available over MCP as pack_asset.

molen asset stage --out-dir

Copy registered assets' runtime files (packed variant when requested) into a browser-servable directory and write assets.index.json (id -> URL). Fails on stale assets.

molen asset stage --out-dir <d> [--variant ktx2] [--require-variant] [--clean] [--project <path>]

Parameter	Type	Required	Description
outDir	string	yes	Output directory (created).
variant	string	no	Stage this packed variant instead of the main GLB.
requireVariant	boolean	no	Fail when an asset lacks the variant (default: warn).
clean	boolean	no	Remove a previous staging output first (default false).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
Also available over MCP as stage_assets.

Audio

Hear what a scene would play without a browser, and build sound banks with provenance.

molen audio plan

Run a scene headlessly and list the sounds it would play: looping voices with start/stop ticks, peak gain and pitch range, one-shots by tick, audio.* script events, and unknown sound ids or signals. Hear a scene's audio annotations without a browser.

molen audio plan <scene|name> --ticks <N> [--bank <bank.json,…>] [--commands <f>] [--setup <m>] [--listener <entity>] [--mode <walk|drive|fly>] [--weather <profile>] [--daylight <0..1>] [--project <project.json>] [--json]

Parameter	Type	Required	Description
scenePath	string	yes	Scene file path or project scene name.
ticks	int>0	yes	Ticks to simulate.
bankPaths	string[]	no	molen/soundbank@1 files (default: every provides.soundbank in the project's packs).
commandsPath	string	no	JSON array (or {commands:[...]}) of command envelopes.
setupModule	string	no	ESM module exporting setup(world, manifest).
listener	string	no	Entity whose transform is the listener (default: the scene camera).
mode	string	no	listener.mode for rules: walk, drive, fly…
weather	string	no	Weather profile: sunny, partly-cloudy, overcast, rain, snow, fog.
daylight	number	no	sky.daylight 0 (night) – 1 (day); default 1.
projectPath	string	no	Explicit project.json (default: walk up from cwd).
Also available over MCP as plan_audio.

molen audio import

Add an audio clip to a molen/soundbank@1 file: copy it beside the bank, hash it, probe its duration, and record license and provenance. --append adds a variation to an existing sound.

molen audio import <file> --id <sound.id> --bank <bank.json> --license <spdx> [--source <url>] [--site s] [--author a] [--prompt p] [--generator g] [--description d] [--loop] [--loop-start s] [--loop-end s] [--bus b] [--gain g] [--duration s] [--append] [--copy-to <dir>]

Parameter	Type	Required	Description
file	string	yes	Audio file (MP3 recommended; WAV and Ogg accepted).
id	string	yes	Sound id, e.g. "ambience.rain.medium".
bankPath	string	yes	Sound bank JSON to update (created when missing).
license	string	yes	SPDX license of the recording, e.g. "CC0-1.0".
source	string	no	Page of the original recording.
site	string	no	Origin site: freesound, kenney, opengameart, …
author	string	no	Recordist or creator.
prompt	string	no	Generation prompt, for generated clips.
generator	string	no	Generator/model name, for generated clips.
description	string	no	What it sounds like (agents choose sounds by it).
loop	boolean	no	Loop the clip (ambience, engines).
loopStart	number	no	Loop start in seconds.
loopEnd	number	no	Loop end in seconds.
bus	string	no	Default bus: music, ambience, sfx, ui, voice.
gain	number	no	Base gain (default 1).
durationS	number	no	Duration in seconds; overrides the probed value.
append	boolean	no	Add as another variation of an existing sound.
copyTo	string	no	Directory under the bank for copied files (default audio).
Also available over MCP as import_sound.

molen audio check

Check a molen/soundbank@1 file and every clip it names: files present, hashes unchanged, durations and loop points consistent, provenance recorded; prints a license summary.

molen audio check <bank.json>

Parameter	Type	Required	Description
bankPath	string	yes	Sound bank JSON.
Also available over MCP as check_soundbank.

Materials and textures

Bake procedural material graphs and round-trip hand-painted UV templates.

molen material bake

Bake a material graph / palette ref to a PNG texture.

molen material bake <matgraph.json> -o <png>  [--ref palette:#rrggbb]

Parameter	Type	Required	Description
path	string	no	Material graph JSON path.
inline	object	no	An inline molen/matgraph@1 document (MCP).
ref	string	no	A material ref, e.g. palette:#rrggbb.
outPath	string	yes	Output PNG path.
Also available over MCP as rasterize_material.

molen uvpaint apply

Import a painted UV template: mask to the island map and dilate the gutters.

molen uvpaint apply <painted.png> --islands <map.png> -o <out.png> [--no-mask] [--dilate N]

Parameter	Type	Required	Description
paintedPath	string	yes	Painted texture (from an image model).
islandMapPath	string	yes	Island map (flat-filled islands on a dark background).
outPath	string	yes	Output PNG path.
maskToIslands	boolean	no	Mask paint to the islands (default true).
dilationPx	int>=0	no	Gutter dilation in pixels.
Also available over MCP as apply_uv_paint.

Worldgen

Outlines and labeled polygons into styled buildings and deterministic props.

molen worldgen preview

Generate buildings from a style pack in Node and render them headlessly (turntable PNGs). Default batch: one building of every footprint class.

molen worldgen preview [style.archstyle.json] [--pack p] [--style id] [--batch f] [--scatter id] [--ground flat|slope] [--angles N] [--size WxH] --out <png>

Parameter	Type	Required	Description
stylePath	string	no	A standalone molen/archstyle@1 document to preview.
packPath	string	no	Style pack: a stylepack.json or its directory, or a content pack file, URL or source directory (default: the project's content packs).
styleId	string	no	Force every building onto this style id.
batchPath	string	no	A molen/worldgen-batch@1 document (default: the lineup).
scatterId	string	no	Scatter rule set for the batch scatter request.
ground	`'flat'	'slope'`	no
angles	int>0	no	Turntable angles (default 1).
size	[w,h]	no	Viewport in pixels (default 1280x720).
outPath	string	no	PNG path (CLI: --out); MCP returns the images directly.
Also available over MCP as worldgen_preview.

molen worldgen bake

Generate buildings from a batch document or one outline and bake them to a glTF asset with a molen/asset@1 sidecar.

molen worldgen bake [batch.json] [--outline "x,z;x,z;..."] [--style id] [--pack p] --out <assets-dir> [--id id] [--ground flat|slope] [--project <project.json>] [--force]

Parameter	Type	Required	Description
batchPath	string	no	A molen/worldgen-batch@1 document.
outline	string	no	One building outline "x,z;x,z;..." in meters (with styleId).
styleId	string	no	Style id for the outline, or forced onto every building.
packPath	string	no	Style pack: a stylepack.json or its directory, or a content pack file, URL or source directory (default: the project's content packs).
outDir	string	yes	Assets root; the asset lands in <outDir>/<id>/.
id	string	no	Asset id (default: the batch name).
ground	`'flat'	'slope'`	no
projectPath	string	no	Explicit project.json (default: walk up from cwd).
force	boolean	no	Replace an existing asset directory.
Also available over MCP as worldgen_bake.

molen worldgen stats

Generate one real terrain-package tile in Node and report counts, histograms, sizes, timings, and determinism; optionally dump the adapted batch.

molen worldgen stats <terrain-package.json> [--tile z/x/y | --auto] [--pack p] [--atlas a] [--style id] [--quality q] [--dump batch.json] [--json]

Parameter	Type	Required	Description
packagePath	string	yes	terrain-package.json path.
tile	string	no	"z/x/y" tile address (default: the package center).
auto	boolean	no	Search the tiles around the center for the most buildings.
packPath	string	no	Style pack: a stylepack.json or its directory, or a content pack file, URL or source directory (default: the project's content packs).
atlasPath	string	no	Region atlas: a world.atlas.json, or a content pack that provides one (default: the project's content packs).
styleId	string	no	Force every building onto this style id.
quality	`'economy'	'balanced'	'high'`
dumpPath	string	no	Write the adapted molen/worldgen-batch@1 here.
Also available over MCP as worldgen_stats.

Ambient life

Bake real road, rail and path networks so NPC traffic can run in any scene.

molen network bake

Bake the roads, railways and paths of a local terrain package into a molen/transport-network@1 document for ambient traffic in scenes without map tiles.

molen network bake <terrain-package.json> (--tile z/x/y [--radius n] | --bbox w,s,e,n) --out network.json [--classes road,rail,path] [--heights] [--json]

Parameter	Type	Required	Description
packagePath	string	yes	terrain-package.json path (local PMTiles archives).
tile	string	no	Centre tile "z/x/y" at the finest features level.
radius	number	no	Tiles around the centre tile to include (default 0).
bbox	number[4]	no	Area [west, south, east, north] in degrees, instead of tile.
classes	string[]	no	Classes to keep: 'road', 'rail', 'path' (default all).
outPath	string	yes	Write the transport-network document here.
heights	boolean	no	Include surface heights from the elevation (default flat).
Also available over MCP as network_bake.

Figures

Stylized humans, bipeds and quadrupeds: presets, descriptors, rigs and gaits.

molen figure preview

Render figure presets, a molen/figure@1 descriptor, or a built-in lineup headlessly from turntable angles or the art-review view set (PNGs).

molen figure preview [descriptor.figure.json] [--preset id[,id]] [--lineup humans|bodies|species|all] [--mode idle|walk|run|sit|jump|fall] [--tick N] [--tier 0|1|2] [--angles N|review] [--size WxH] --out <png>

Parameter	Type	Required	Description
preset	`string	string[]`	no
descriptorPath	string	no	A molen/figure@1 document to render.
descriptor	object	no	An inline descriptor (the figure component shape).
lineup	`'humans'	'bodies'	'species'
mode	`'idle'	'walk'	'run'
tick	int>=0	no	Simulation tick to pose at (default 15).
tier	`0	1	2`
angles	`int>0	'review'`	no
size	[w,h]	no	Viewport in pixels (default 1280x720).
outPath	string	no	PNG path (CLI: --out); MCP returns the images directly.
Also available over MCP as figure_preview.

molen figure presets

List the shipped figure presets with their resolved descriptors.

molen figure presets [--archetype biped|quadruped] [--json]

Parameter	Type	Required	Description
archetype	`'biped'	'quadruped'`	no
Also available over MCP as list_figure_presets.

Server

Expose every operation above to an agent over MCP.

molen mcp

Start the MCP server over stdio (exposes every mcpTool in this catalog).

molen mcp

No parameters. CLI only — not exposed over MCP.

Other operations

Added since this page was last curated.

molen pack build

Build a content pack (molen/pack@1 zip) from a source directory holding molen-pack.source.json. Writes <id>-<hash>.zip and updates index.json in outDir.

molen pack build <sourceDir> --out-dir <d> [--no-solid]

Parameter	Type	Required	Description
sourceDir	string	yes	Pack source directory (holds molen-pack.source.json).
outDir	string	yes	Output directory for the pack file and index.json.
solid	boolean	no	Group small text files into compressed solid blocks (default: the source's setting).
Also available over MCP as build_pack.

molen pack inspect

Summarize a content pack: id, version, contentHash, sizes, solid blocks, asset ids, roles and the largest files.

molen pack inspect <source>

Parameter	Type	Required	Description
source	string	yes	Built pack file, pack source directory, or http(s) URL.
Also available over MCP as inspect_pack.

molen pack verify

Read every file of a content pack checking CRC and sha256, validate each JSON document against its registered schema, and check asset sidecar hashes against their models.

molen pack verify <source>

Parameter	Type	Required	Description
source	string	yes	Built pack file, pack source directory, or http(s) URL.
Also available over MCP as verify_pack.

molen pack extract

Write every file of a content pack into a directory, with a molen-pack.source.json that builds it back to the same content.

molen pack extract <source> --out-dir <d>

Parameter	Type	Required	Description
source	string	yes	Built pack file or http(s) URL.
outDir	string	yes	Directory to write the files into.
Also available over MCP as extract_pack.

molen pack fetch

Download content packs (a pack URL, or a molen/pack-index@1 URL) into the project, list them in index.json in the download directory (so a page can open them), and pin them in project.json packs with their contentHash, so the project runs offline.

molen pack fetch <url> [ids…] [--out-dir <d>] [--project <path>]

Parameter	Type	Required	Description
url	string	yes	URL of a pack file, or of a pack index.
ids	string[]	no	With an index URL, fetch only these pack ids (default: all).
outDir	string	no	Download directory (default: packs/ beside project.json).
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
Also available over MCP as fetch_pack.

molen scripts check

Type-check the scene's scripts against their generated declarations: component typos, bad command payloads, unguarded reads.

molen scripts check [--project <path>]

Parameter	Type	Required	Description
projectPath	string	no	Explicit project.json (default: walk up from cwd).
cwd	string	no	Directory to discover the project from (default: process.cwd()).
Also available over MCP as check_scripts.