CLI reference

Full command reference for the milli CLI. For setup recipes (Neovim splash, terminal screensaver, fastfetch, etc.) see recipes.md. For the library API and .milli format, see api.md.

• milli image
• milli play
• milli convert
• milli export
• milli fastfetch
• Render modes
• Export targets

milli image

Render a single image to ANSI-colored ASCII on stdout. The default command — milli pic.png is shorthand for milli image pic.png.

milli image <path> [options]

Options:

Flag	Default	Description
-w, --width <cols>	terminal width	Columns (chars wide)
-h, --height <rows>	terminal height - 2	Rows (chars tall)
-m, --mode <mode>	match	Render mode (match / ramp / braille)
-s, --symbols <set>	ascii	Ramp-mode glyph set (ascii / block / braille / all)
--no-color	off	Monochrome output
--bg	auto (match mode)	Render background color per cell
--invert	off	Invert luminance ramp
--dither	off	Floyd-Steinberg dithering (ramp mode only)
--aspect <ratio>	0.5	Char width/height ratio (tune if output is stretched)

Examples:

milli image pic.png                              # auto-fit to terminal
milli image pic.png -w 60                        # fixed width
milli image pic.png -m ramp --dither             # classic ASCII, dithered
milli image pic.png -m braille --no-color        # monochrome braille
milli image pic.png > out.ansi                   # pipe to file

milli play

Play a GIF (or pre-baked .milli file) as a terminal animation. Alt-screen, hidden cursor, Ctrl+C restores cleanly. Only changed cells are rewritten each frame, so it's cheap over SSH.

milli play <path> [options]

Options:

Flag	Default	Description
-w, --width <cols>	terminal width	Columns
-h, --height <rows>	terminal height - 2	Rows
-m, --mode <mode>	match	Render mode
-s, --symbols <set>	ascii	Ramp-mode glyph set
--no-color	off	Monochrome
--no-loop	loops by default	Play once and exit
--fps <n>	source delays	Override framerate
--aspect <ratio>	0.5	Char w/h ratio
--inline	off	Paint in-place (no alt-screen) for composition with other output
--at <x,y>	1,1	Inline anchor as 1-based terminal cell

Examples:

milli play anim.gif                              # loops forever, Ctrl+C to exit
milli play anim.gif --no-loop                    # play once
milli play anim.gif -w 80 -m ramp --fps 12
milli play anim.milli                            # pre-baked, instant start
milli play anim.milli --inline --at 5,3          # animate at col 5 row 3, no alt-screen

--inline is the building block for the animated fastfetch recipe and any composition where you want milli to paint into a specific region without taking over the whole terminal.

milli convert

Bake an image or GIF into a .milli file — a gzipped, delta-encoded frame format. Playback needs only the core engine (no sharp, no image decoder), so .milli files start instantly and ship with your app.

milli convert <input> <output.milli> [options]

Options:

Flag	Default	Description
-w, --width <cols>	100	Target columns
-h, --height <rows>	40	Target rows
-m, --mode <mode>	match	Render mode
-s, --symbols <set>	ascii	Ramp-mode glyph set
--no-loop	loops by default	Mark as play-once
--aspect <ratio>	0.5	Char w/h ratio

Examples:

milli convert hero.gif hero.milli -w 80 -m match
milli convert logo.png logo.milli -w 40             # single-frame .milli is fine

For format details (keyframe + delta encoding, glyph dedupe, etc.) see api.md#milli-format.

milli export

Emit frames as source code for another language/runtime. For Neovim, Go TUIs (Bubbletea), or any project where you want ASCII animation without a dependency on Node.

milli export <input> <outdir> [options]

Options:

Flag	Default	Description
-t, --target <target>	go	go / lua / json
-w, --width <cols>	80	Columns
-h, --height <rows>	-	Rows cap (optional)
-m, --mode <mode>	match	Render mode
-s, --symbols <set>	ascii	Ramp-mode glyph set
-p, --package <name>	outdir basename	Go package name
--aspect <ratio>	0.5	Char w/h ratio
--no-helper	helper on	Skip helper file (Go target only; Lua is always data-only)
--no-color	Lua target: color on	Omit per-cell color runs (smaller file)
--no-bg	bg kept	Fully transparent background (sugar for --bg-threshold 1)
--bg-threshold <n>	0	Luma-gated transparency 0..1 (drop bg when cell's bg luma below threshold)

Examples:

# Go: frames.go + splash.go (Tick/Render helper for Bubbletea)
milli export anim.gif ./out -t go -p bootsplash -w 50

# Lua: emits frames.lua (data-only). Drop into milli.nvim's splashes dir.
milli export anim.gif ./out -t lua -w 60 --no-bg

# JSON: frames.json with full { glyph, fg, bg } grid per frame
milli export anim.gif ./out -t json -w 50

milli fastfetch

Run fastfetch with an animated .milli logo. Wraps the --inline paint trick into a single command — no shell wrapper, no manually-sized blank-logo file.

milli fastfetch <path.milli> [options]

Options:

Flag	Default	Description
--at <pos>	3,2	Inline anchor as x,y (1-based). Match your fastfetch logo padding.
--ff-args <args>	-	Extra args passed through to fastfetch (whitespace-split).

What it does:

1. Reads the .milli header → derives the logo column dimensions (cols × rows).
2. Writes a blank-spaces placeholder file to $TMPDIR so fastfetch reserves the logo column.
3. Spawns fastfetch --logo <tmp> --logo-type file-raw [your --ff-args]. Fastfetch prints info on the right and exits.
4. Loops the animation in the reserved column via inline play (no alt-screen). Ctrl+C exits and the cursor lands below.

Examples:

# bake once, then run
milli convert clip.gif ~/.config/milli/anim.milli -w 50 -m match
milli fastfetch ~/.config/milli/anim.milli

# pass a custom fastfetch config
milli fastfetch ~/.config/milli/anim.milli --ff-args "--config minimal.jsonc"

# tweak inline anchor (default 3,2 matches padding top:1 left:2)
milli fastfetch ~/.config/milli/anim.milli --at 4,3

Make it your default fastfetch:

# ~/.zshrc / ~/.bashrc
alias fastfetch='milli fastfetch ~/.config/milli/anim.milli'

Use command fastfetch (or \fastfetch) when you want the real one-shot fastfetch.

Requires fastfetch on $PATH — install from fastfetch-cli/fastfetch.

milli text

Animate any text with a procedural effect. No source image — frames are computed from a built-in block font, so it works offline, loops forever live, and bakes to any export target.

milli text <string> [options]

Options:

Flag	Default	Description
-e, --effect <name>	fire	fire / glitch / wave / matrix / dissolve / typewriter / pulse / rainbow
-c, --color <hex>	#00ffbe	Base color (effects that take one: glitch, dissolve, typewriter, pulse)
--fps <n>	30	Frame rate
--scale <n>	2	Horizontal cells per font pixel (vertical is half; bigger = larger text)
--seed <n>	1337	Random seed — same seed, same animation
--seconds <n>	forever	Stop live playback after n seconds
-o, --export <outdir>	-	Bake frames to files instead of playing
-t, --target <t>	lua	Export target: lua / go / json / milli
--frames <n>	one loop	Baked frame count (default: the effect's clean loop period)
-p, --package <name>	slug	Go package name (go target)

Examples:

# flaming text in your terminal, right now
milli text "MILLI" -e fire

# glitchy banner, custom color
milli text "SYSTEM ONLINE" -e glitch -c "#ff0044"

# bake a matrix-rain reveal of your name for your nvim dashboard
milli text "NEOVIM" -e matrix -o ./out -t lua
cp ./out/neovim-matrix.lua ~/.config/nvim/lua/milli/splashes/myname.lua

# ship a .milli for fastfetch / play
milli text "YOLO" -e wave -o ./out -t milli
milli play ./out/yolo-wave.milli

Effect cheat sheet: fire burns the letters (DOOM-style heat sim), glitch does RGB channel-split + row tearing, wave ripples with a hue sweep, matrix reveals the text behind falling rain, dissolve blows letters into particles and reassembles, typewriter types with a blinking cursor, pulse breathes with a neon glow halo, rainbow scrolls a gradient.

milli shader

Run a real-time procedural shader in the terminal. Pure math — no assets, never repeats, fills whatever size you give it.

milli shader <name> [options]

Shaders: plasma, rain (matrix rain), doomfire, starfield, tunnel, waves.

Options:

Flag	Default	Description
-w, --width <cols>	terminal	Columns
-h, --height <rows>	terminal	Rows
--fps <n>	30	Frame rate
--hue <deg>	per-shader	Base hue 0-360 (recolor rain, plasma, tunnel, waves, starfield)
--seed <n>	1337	Random seed
--seconds <n>	forever	Stop after n seconds (screensaver-with-timeout)
-o, --export <outdir>	-	Bake frames instead of playing
-t, --target <t>	lua	lua / go / json / milli
--frames <n>	loop period	Baked frame count

Examples:

# fullscreen matrix rain — instant screensaver
milli shader rain

# purple plasma, 10-second burst
milli shader plasma --hue 280 --seconds 10

# bake DOOM fire into a .milli for fastfetch
milli shader doomfire -w 50 -h 14 -o ./out -t milli
milli fastfetch ./out/doomfire.milli

milli.nvim ships native Lua ports of plasma, rain, doomfire, and starfield — those run live inside Neovim with zero baked frames (:MilliShader rain). Baking is for the other targets or fixed-size loops.

Render modes

Mode	What it does	Best for
match	Pixel-perfect glyph matching: for each cell, picks the glyph + fg/bg pair whose rendered pixels best approximate the source region (sobel-weighted MSE over a pre-baked font atlas). Color is essential here.	Photos, screenshots, logos where detail matters
ramp	Classic luminance ramp: maps brightness to a gradient of characters (" .:-=+*#%@" by default). Pair with --dither for Floyd-Steinberg error diffusion.	Stylized / retro look, monochrome, low-res
braille	Treats each cell as a 2×4 sub-pixel grid using Unicode braille characters. Higher effective resolution, mono-colored per cell.	High-detail line art, dashboard splashes, diagrams

Tip: for nvim dashboards and TUIs, braille + --no-bg produces a clean look that blends with any colorscheme.

Export targets

Go / Bubbletea

milli export anim.gif ./bootsplash -t go -p bootsplash -w 50

Emits:

• frames.go — frame data (ANSI strings per frame, delays)
• splash.go — Bubbletea helper with Tick, Render, TickMsg, DoneMsg

For wiring into a Bubbletea model, see recipes.md#bubbletea-tui-splash.

Lua / Neovim

milli export anim.gif ./out -t lua -w 60 --no-bg

Emits frames.lua — a data module with frame glyphs + per-cell color runs.

Use with milli.nvim — the companion plugin ships the runtime (paint, loop, extmark coloring) and dashboard presets. See recipes.md#neovim-dashboard-splash.

JSON

milli export anim.gif ./out -t json -w 50

Emits frames.json — full { cols, rows, delays, frames: [[{ glyph, fg, bg }]] }. Use for custom runtimes (Python/textual, Rust/ratatui, web players, etc).

Want a first-class helper for your language? Open an issue — if there's demand, we'll ship it (Go and Neovim already have dedicated paths).