Terminal UI beta

mold includes an interactive terminal UI for browsing models, tuning parameters, generating images with live progress, and previewing results — all without leaving the terminal.

Built on ratatui with Kitty graphics protocol support for pixel-perfect image preview in terminals like Ghostty, kitty, and WezTerm. Falls back to halfblock rendering in other terminals.

Beta

The TUI is under active development. Core generation, model management, gallery, and image preview work well. Some features (prompt expansion, theme customization) are planned but not yet implemented.

Quick Start

mold tui

The TUI launches in the Generate view with your cursor in the prompt field. Type a prompt, press Enter, and watch the progress panel as your image generates. The result appears in the Preview panel and is saved to ~/.mold/output/.

TIP

The tui feature must be compiled in. Pre-built releases and the Nix package include it by default. If building from source, add --features tui to your build command.

Auto-Start Server

By default, mold tui automatically starts a background mold serve process if no server is already running. This keeps models hot between generations for faster subsequent runs. The server is killed when you quit the TUI.

• mold tui — auto-starts server on localhost:7680
• mold tui --local — skip server, use local GPU only
• mold tui --host http://gpu:7680 — connect to an existing remote server

Server Logs

When the TUI auto-starts a background server, logs are written to ~/.mold/logs/ with daily rotation. This is useful for debugging generation failures since the server's stderr is suppressed while the TUI controls the terminal.

Log files follow the naming pattern mold-server.YYYY-MM-DD.log and are automatically cleaned up after 7 days (configurable via logging.max_days in ~/.mold/config.toml).

To view live logs while the TUI is running, open a second terminal:

tail -f ~/.mold/logs/mold-server.$(date +%Y-%m-%d).log

You can also enable file logging for manual mold serve with --log-file, or permanently via the config file:

[logging]
level = "info"
file = true
# dir = "~/.mold/logs"
# max_days = 7

Views

The TUI has three main views, shown as tabs at the top of the screen:

View	Purpose
Generate	Write prompts, tune parameters, generate images
Gallery	Browse generated images with preview
Models	View installed and available models

Switch views with Esc then 1/2/3, arrow keys, or click the tabs. Alt+1/Alt+2/Alt+3 works from anywhere.

Generate View

The main workspace with five panels:

• Prompt — Multi-line text area (Shift+Enter for newlines, emacs keybindings)
• Negative — (CFG models only) Describes what to avoid
• Parameters — Model, dimensions, steps, guidance, seed, and more
• Info — Model description, system memory, process memory usage
• Preview — Generated image with Kitty/sixel/halfblock rendering

Editing Parameters

Navigate to Parameters with Tab or click, then:

• j/k or arrow keys to move between fields
• +/- or left/right to adjust numeric values
• Enter or click to activate a field:
  • Model — opens the fuzzy model selector
  • Seed (mode row) — cycles random / fixed / increment
  • Seed (value row) — opens seed value input popup
  • Format / Mode / Expand / Offload — toggles the value
  • Scheduler — cycles through Ddim, Euler Ancestral, UniPC
  • Reset — restores all parameters to model defaults (keeps prompt)
  • Unload — unloads the model from GPU to free memory

Seed Modes

Cycle with Ctrl+R or +/- on the Seed field:

Mode	Behavior
random	New random seed each generation
fixed	Same seed every time (reproducibility)
increment	Seed +1 after each generation

Press Enter on the Seed value row to type an exact value.

Model Selector

Press Enter on the Model field or Ctrl+M from anywhere:

• Type to fuzzy-filter the model list
• j/k, arrow keys, or scroll wheel to navigate
• Enter to select — parameters update to model defaults
• Esc to cancel

Prompt History

Previous prompts persist across sessions in ~/.mold/prompt-history.jsonl:

• Up/Down arrows at top/bottom of prompt recall history
• Ctrl+P/Ctrl+N also navigate history
• / in navigation mode opens fuzzy search over all prompts

Shell Keybindings

The prompt editor supports standard emacs/shell keybindings:

Key	Action
Ctrl+A	Beginning of line
Ctrl+E	End of line
Ctrl+K	Kill to end of line
Ctrl+U	Kill to start
Ctrl+W	Delete word back
Ctrl+D	Delete forward
Ctrl+F	Forward char
Ctrl+B	Backward char

Gallery View

Browse generated images stored in ~/.mold/output/ (or MOLD_OUTPUT_DIR). Images are displayed as a thumbnail grid with cached 256x256 thumbnails for fast loading. Only images with embedded mold:parameters metadata are shown (PNG and JPEG).

Grid Mode

Key	Action
h/j/k/l	Navigate the grid
Arrow keys	Navigate the grid
Enter	Open detail view
e	Load into Generate (edit)
d	Delete image (with confirmation)
o	Open in system viewer
Esc	Back to Generate

Detail Mode

Press Enter on a grid thumbnail to see the full image with all metadata.

Key	Action
e	Load into Generate (edit)
r	Regenerate immediately
d	Delete image
o	Open in system viewer
j/k	Previous / next image
Esc	Back to grid

Thumbnails

Thumbnails are cached at ~/.mold/cache/thumbnails/ and generated automatically on first scan and after each generation. Delete the cache directory to force regeneration.

Models View

See all installed and available models with family, size, defaults, and status.

Key	Action
j/k	Navigate the model list
Enter	Set as default model
p	Pull (download) a model
u	Unload the active model (GPU)
Esc	Back to Generate

Navigation

Press Esc to enter navigation mode, where number keys and arrows switch views.

Global Shortcuts

Key	Action
Esc	Unfocus / navigation mode
1 / 2 / 3	Switch views (in navigation mode)
Left / Right	Cycle views (in navigation mode)
Alt+1 / 2 / 3	Switch views (from anywhere)
Tab	Cycle focus to next panel
Shift+Tab	Cycle focus to previous panel
Ctrl+C	Quit
q	Quit (when not in a text field)
?	Show help overlay

Generate Shortcuts

Key	Context	Action
Enter	Prompt	Start generation
Enter	Parameters	Activate field (selector/toggle)
Ctrl+G	Any	Start generation
Ctrl+M	Any	Open model selector
Ctrl+R	Any	Cycle seed mode
+/-	Parameters	Adjust numeric value
j/k	Parameters	Navigate fields

Mouse Support

• Click tabs to switch views
• Click panels to focus them
• Click parameter rows to select and activate
• Click gallery thumbnails to select, double-click for detail view
• Click model rows to select
• Scroll wheel navigates lists and popups

Session Persistence

All settings are saved to ~/.mold/tui-session.json after each generation and restored on next launch:

• Prompt and negative prompt text
• Model selection
• All generation parameters (dimensions, steps, guidance, seed mode, batch, format, scheduler, lora, expand, offload, strength)

Use Reset in the Actions section of Parameters to restore model defaults without losing your prompt. Unload frees GPU memory by unloading the active model.

Generated images are saved to ~/.mold/output/ by default (override with MOLD_OUTPUT_DIR env var or output_dir in config). All images include embedded PNG metadata that preserves the full generation parameters, making them portable across machines.

Info Panel

The Info panel below Parameters shows:

• Model description from the manifest
• System memory — free and available (macOS unified memory / NVIDIA VRAM)
• Mold memory — total physical footprint of all mold processes (includes mmap'd model weights)

Server Fallback

The TUI uses a three-mode inference system:

Mode	Behavior
auto	Try server first, fall back to local GPU (default)
local	Force local GPU only
remote	Force remote server only (error if unreachable)

Cycle with +/- on the Mode field. The Host field (visible in auto/remote mode) can be edited with Enter to point at a custom server. Host input is normalized automatically: hal9000 becomes http://hal9000:7680, hal9000:8080 becomes http://hal9000:8080, and full URLs like https://gpu.example.com are used as-is. The TUI verifies connectivity before switching.

Image Preview

The TUI auto-detects your terminal's graphics protocol at startup:

Protocol	Terminals	Quality
Kitty	Ghostty, kitty, WezTerm	Pixel-perfect
Sixel	foot, xterm, mlterm	Full color
iTerm2	iTerm2, Hyper	Full color
Halfblocks	Everything else	Unicode blocks

Building with TUI Support

The TUI is behind the tui feature flag on mold-ai:

macOS (Metal)

cargo build --release -p mold-ai --features metal,tui

Linux (CUDA)

cargo build --release -p mold-ai --features cuda,tui

All features

cargo build --release -p mold-ai --features metal,preview,discord,expand,tui

The Nix flake, pre-built releases, and Docker images include the TUI by default.

Theme

The TUI uses a Catppuccin Mocha color palette. Theme customization via config.toml is planned for a future release.