CLI Reference

Flint’s CLI is the primary interface for all engine operations. Below is a reference of available commands.

Commands

The seven music commands are documented on their own page: Music Commands.

The play Command

Launch a scene as an interactive first-person experience with physics:

flint play demo/phase4_runtime.scene.toml
flint play levels/tavern.scene.toml --schemas schemas --fullscreen

--music-volume 0 is the quickest way to audition a scene’s sound design without its score. See Audio: Mixer Buses.

The standalone flint-player binary takes the same flags plus --msaa <1|4> (default 1) for multisample anti-aliasing of the scene passes; flint play does not expose --msaa.

Player Controls (Defaults)

These are the built-in defaults. Games can override any binding via input config files (see Physics and Runtime: Input System).

The per-effect F-keys of earlier releases (F1 debug mode, F4 shadows, F5 bloom, F6 post-processing and so on) are gone; all of those toggles and their parameters live in the F4 menu (see Post-Processing: The Rendering & Effects menu). F9, ` and \ exist only when the player is built with the default debug-hud feature.

Gamepad controllers are also supported when connected. Bindings for gamepad buttons and axes can be configured in input config TOML files.

Debug Panels (F3)

F3 opens live tuning panels for whichever systems the current scene actually uses. Each panel is created only when its driving component is present, so a scene with no ocean never sees an ocean panel and a scene with no panels at all logs a note instead. Panels are fold-open headers distributed across up to three size-balanced columns.

Built-in panels:

The full roster and the DebugPanel trait are described in Debug Panels.

Edits apply live through the world’s components. Commit to File writes the current values back into the scene TOML, so a tuning session ends as a diff rather than as notes. Values a game script owns each frame (a day counter, a published factor) are deliberately never committed.

Games can add their own panels for their own components; unknown panels simply take a default size weight in the column layout.

Escape releases the mouse so panels can be clicked; clicking the world recaptures it.

The play command requires the scene to have a player archetype entity with a character_controller component. Physics colliders on other entities define the walkable geometry.

Game Project Pattern

Games that define their own schemas, scripts, and assets use multiple --schemas paths. Game projects typically live in their own repositories with the engine included as a git subtree at engine/. The engine schemas come first, then the game-specific schemas overlay on top:

# From a game project root (engine at engine/)
cargo run --manifest-path engine/Cargo.toml --bin flint-player -- \
  scenes/level_1.scene.toml \
  --schemas engine/schemas \
  --schemas schemas

This loads the engine’s built-in components (transform, material, rigidbody, etc.) from engine/schemas/, then adds game-specific components (health, weapon, enemy AI) from the game’s own schemas/. See Schemas: Game Project Schemas for directory structure details and Building a Game Project for the full workflow.

Standalone Player Binary

The player is also available as a standalone binary for distribution:

cargo run --bin flint-player -- demo/phase4_runtime.scene.toml --schemas schemas

# With game project schemas (from a game repo with engine subtree)
cargo run --manifest-path engine/Cargo.toml --bin flint-player -- \
  scenes/level_1.scene.toml --schemas engine/schemas --schemas schemas

The render Command

Render a scene to a PNG image without opening a window:

flint render demo/phase3_showcase.scene.toml --output hero.png --schemas schemas
flint render scene.toml -o shot.png --distance 20 --pitch 30 --yaw 45 --target 0,1,0 --no-grid

When no camera flags are given, the render starts from the scene’s [camera] block if it has one. The camera and post flags override the scene’s authored [camera] and [post_process] values.

flint render runs no scripts. Anything your game drives from a script — a render mode, a time of day, a floating hull, an animated character — will not happen. The render-mode flags exist precisely so a stylized frame can be captured without one. For script-driven world state, bake a fixture scene with the values you want; for animation, note that skinned meshes render at bind pose headlessly. To capture a posed frame of a rigged model, use the model previewer instead: flint edit model.glb --render out.png --anim-time 1.5 (optionally with --clip, --layer or --sequence).

The edit Command

Unified interactive editor that auto-detects file type and opens the appropriate tool:

flint edit levels/demo.scene.toml              # Scene viewer (hot-reload)
flint edit levels/demo.scene.toml --spline     # Spline/track editor
flint edit models/character.glb                # Model previewer (orbit camera)
flint edit models/character.glb --watch        # Model previewer with file watching
flint edit specs/oak_tree.procgen.toml         # Procgen previewer (mesh/texture)
flint edit specs/stone_wall.procgen.toml       # Texture pipeline editor (if pipeline pattern)
flint edit terrain.terrain.toml                # Terrain editor

File Type Detection

Common Flags

Model Previewer Flags

Scene Viewer Controls

The viewer applies the scene’s [post_process] block on load; the F4 menu’s “authored” switch flips between those values and the viewer defaults. The earlier F1 (debug mode), F2 (wireframe overlay) and F4 (shadows) keys were folded into the F4 menu.

When an entity is selected, a translate gizmo appears with colored axis arrows (red = X, green = Y, blue = Z) and plane handles. Click and drag an axis or plane to move the entity. Position changes can be undone/redone and saved back to the scene file.

Spline Editor Controls (--spline)

Legacy aliases: flint serve, flint preview, flint gen-preview, flint tex-edit, flint terrain-edit, and flint spline-edit still work. They are hidden subcommands that open the same tools flint edit dispatches to; they are omitted from flint --help.

The asset generate Command

Generate assets using AI providers:

flint asset generate texture -d "rough stone wall" --style medieval_tavern
flint asset generate model -d "wooden chair" --provider meshy --seed 42
flint asset generate audio -d "tavern ambient noise" --duration 10.0

Generated assets are automatically stored in content-addressed storage and registered in the asset catalog with a .asset.toml sidecar. Models are validated against style constraints after generation.

The gen Command

Run a procedural generation spec to produce meshes (GLB) or textures (PNG):

flint gen specs/oak_tree.procgen.toml -o tree.glb
flint gen specs/stone_wall.procgen.toml -o wall.png
flint gen specs/oak_tree.procgen.toml --dry-run
flint gen specs/oak_tree.procgen.toml --seed 42 -o tree.glb
flint gen specs/oak_tree.procgen.toml --batch 10 --seed-start 0

The prefab view Command

Preview a prefab template in the interactive viewer:

flint prefab view prefabs/kart.prefab.toml --schemas engine/schemas --schemas schemas

This command loads the .prefab.toml template, performs variable substitution, builds a synthetic scene from the expanded entities, and launches the viewer for visual inspection. Useful for verifying prefab structure and appearance without creating a full scene.

Common Flags

Usage

# Get help
flint --help
flint <command> --help

# Examples
flint init my-game
flint edit levels/tavern.scene.toml              # Interactive scene viewer
flint edit models/character.glb --watch           # Model previewer
flint play levels/tavern.scene.toml
flint render levels/tavern.scene.toml -o shot.png
flint gen specs/oak_tree.procgen.toml -o tree.glb
flint query "entities where archetype == 'door'" --scene levels/tavern.scene.toml