MoGen CLI reference

mogen is a single static binary. Every entry point is a subcommand — mogen <subcommand> …. Run mogen --help for the auto-generated short form, or mogen <subcommand> --help for per-command flags.

This page is the long-form reference. For the language those commands operate on, see dsl.md. For the desktop GUI that wraps the same pipeline, see studio.md.

• Common flags and conventions
• build — compile DSL to GLB
• parse — dump the AST
• check — validate a DSL file
• dump-scene — print the lowered scene graph
• inspect — summarise a GLB
• generate — Gemini-driven scene generation
• modify — Gemini-driven edit of an existing .mog
• animate — Gemini edit limited to animation declarations
• repair — auto-fix validation errors with Gemini
• textures — generate PBR textures with Gemini Flash Image
• bench — run a prompt suite and report success rate
• Environment variables
• Exit codes

Common flags and conventions

A few flag patterns repeat across every LLM-driven subcommand (generate, modify, animate, repair, textures, bench):

The seed appears at the top of every generated .mog as a header comment:

// mogen-generate seed=1777210527637284168
// mogen-generate thinking=high
// prompt: A simple four-legged chair.

build

Compile a DSL file to a GLB.

mogen build <input.mog> [--out <output.glb>]

Pipeline. build runs the canonical front-to-back pipeline:

1. Parse the DSL (pest grammar).
2. AST validation — referential and typing errors with source spans.
3. Lower to SceneGraph — module expansion, placement shortcuts, attach solver, animation/skinning lowering.
4. Graph validation — topological invariants (skeleton ancestry, weight sums, …).
5. Export GLB — PBR materials, embedded textures, animation channels, optional skin data, optional sibling-mesh merge.

generate, modify, animate, repair, and textures all converge on this command at the end of their flows. If you've already authored a .mog, build is what you run.

mogen build examples/chair.mog --out chair.glb

parse

Parse a DSL file and print the AST. Useful when debugging grammar errors or checking how a tricky source string lowers.

mogen parse <input.mog>

No GLB is produced. Lowering and validation are skipped.

check

Validate a DSL file. Exits non-zero on any error.

mogen check <input.mog> [--json]

Validation is dual: AST-level (typing, references, unknown attributes) and graph-level (topology, weights, skeleton roots). The two phases produce a unified diagnostic list. Human mode renders via codespan-reporting; JSON mode emits one diagnostic per line in the format the LLM repair loop consumes.

mogen check examples/chair.mog                          # human-readable
mogen check examples/chair.mog --json | jq .            # machine-readable

dump-scene

Lower a DSL file and print the resulting scene graph. Useful for inspecting what an LLM actually emitted, or for diffing two .mog files post-lowering.

mogen dump-scene <input.mog> [--json]

inspect

Read a GLB and print its top-level structure: scenes, meshes, materials, animations, skins, extensions, embedded image sizes.

mogen inspect <output.glb>

The same machinery that powers MoGen Studio's "GLB summary" panel; useful for verifying what actually landed in a release artifact.

generate

Generate a .mog from a natural-language prompt via Gemini, validate it, repair JSON diagnostics in a loop, then compile it to a GLB.

mogen generate "<prompt>" [--out <out.glb>] [--dsl-out <out.mog>] [common LLM flags]

Repair loop. If the generated DSL fails validation, generate re-feeds the JSON diagnostics back to Gemini up to --max-repair-iters times. On the final failure it prints the unfixed diagnostics and exits non-zero, leaving the broken .mog on disk for inspection.

mogen generate "a wooden stool" --out stool.glb
mogen generate "a clockwork dragon" --thinking xhigh --out dragon.glb
mogen generate "a cube" --thinking low --dry-run                  # no API cost beyond one fast call

modify

Apply a natural-language edit to an existing .mog, then revalidate and recompile. The model receives the full DSL and your prompt; the response replaces the file in place (or writes to --dsl-out).

mogen modify <input.mog> "<prompt>" [common LLM flags]

The seed embedded in the input header is preserved across edits unless you override it explicitly. That makes modify reproducible for a given prompt + seed pair.

mogen modify examples/chair.mog "make the legs taller"
mogen modify examples/chair.mog "add armrests" --dsl-out chair_armed.mog --dry-run

animate

Same shape as modify, but the LLM is restricted to animation top-level declarations — joint, clip / track, and the procedural templates (spin, open_close, wave, flap, idle). Geometry, materials, and hierarchy are guaranteed not to change.

mogen animate <input.mog> "<prompt>" [common LLM flags]

mogen animate examples/drone.mog "spin every rotor at 120 rpm"
mogen animate examples/door.mog "make the door swing open over 1.2 seconds"

The flag set matches modify (--out, --dsl-out, --seed, and the common LLM flags). Use this when you want the model focused on motion and not tempted to reshape the scene.

repair

Run the validator against an existing .mog and ask Gemini to fix every diagnostic — with the source excerpt, caret, and fix hint passed in. If the file already validates, repair is a no-op success.

mogen repair <input.mog> [--no-build] [common LLM flags]

Use repair after editing a .mog by hand and breaking validation, or after pasting in a snippet from somewhere else. It's the same machinery the generate / modify / animate repair loops use, exposed as a top-level command.

textures

Generate PBR textures for every material in a .mog. The albedo is LLM-drawn via Gemini 2.5 Flash Image, then locally derived normal, metallic-roughness, and occlusion maps are computed from the albedo (Sobel-from-luminance, variance-based, cavity-based). PNGs are written next to the .mog and the matching *_texture="…" attrs are spliced back into the source via spans (no reformatting).

mogen textures <input.mog> [--style "<hint>"] [--texture-size <N>]

Idempotency. Per slot, materials that already declare a given *_texture attr — or whose target PNG already exists at the planned path — are skipped unless --force is passed. Existing on-disk PNGs still get their *_texture attr spliced into the source, just without an API call or a local re-derivation.

mogen textures examples/chair.mog --style "weathered oak"
mogen textures examples/drone.mog --no-occlusion --texture-size 512
mogen textures examples/chair.mog --dry-run                          # see the plan first

bench

Run a suite of prompts through generate and report success rate and mean token cost. Does not write GLBs.

mogen bench [--prompts <file>] [common LLM flags]

Used as a regression gate during development — the project targets ≥ 80% success rate on the bundled prompt suite.

Environment variables

Exit codes

check --json and the LLM repair loop emit machine-readable diagnostics; everything else uses human-readable formatting via codespan-reporting.