Skip to Content
Veila
Configuration

Preview Screenshot

Preview themes as PNGs with optional mock widget data.

Use veila preview to save a lockscreen PNG without locking.

Previews follow configured widget visibility. Weather flags show mock weather even when the widget is disabled.

Basic Usage

veila preview \
  --config="$HOME/.config/veila/config.toml" \
  --preview-png=/tmp/veila-preview.png \
  --preview-size=1920x1080

No running service or live media is needed.

Flags accept either form:

--preview-png=/tmp/veila-preview.png
--preview-png /tmp/veila-preview.png

# same applies to other preview flags such as --preview-size, --preview-title, etc.

Preview Flags

FlagWhat it does
--config <path>Uses a specific Veila config file for the preview render
--preview-png <path>Required for preview mode. Screenshot PNG path
--preview-size <width>x<height>Sets the output image size, for example 1920x1080
--preview-time <HH:MM>Overrides the clock time in the screenshot
--preview-username <text>Overrides the displayed username label
--preview-weather-location <text>Overrides the displayed weather location label
--preview-weather-condition <name>Overrides the weather icon. (rain, snow, clear-day, etc.)
--preview-weather-temperature <celsius>Overrides the weather temperature in Celsius
--preview-battery-percent <0-100>Overrides the battery percentage
--preview-battery-charging <bool>Overrides the battery charging state with true or false
--preview-title <text>Overrides the now playing track title
--preview-artist <text>Overrides the now playing artist text
--preview-artwork <path>Overrides the now playing artwork image
--preview-hide-widgetsHides weather, battery, now playing and keyboard label together
--preview-hide-weatherHides only the weather widget
--preview-hide-batteryHides only the battery widget
--preview-hide-now-playingHides only the now playing widget
--preview-hide-keyboard-labelHides only the sample keyboard layout label such as EN
--force-emergency-uiRenders the built-in emergency unlock prompt instead of the configured scene

Hide Flag Behavior

--preview-hide-widgets takes priority over individual hide flags.

Grid

Add a grid to check widget positions, backdrop sizes, and spacing. It appears only in preview PNGs.

[visuals.grid]
enabled = true
cell_size = 40
color = "#FFFFFF14"
major_every = 4
major_color = "#FFFFFF26"
KeyWhat it doesDefault
enabledShow or hide the grid overlay.false
cell_sizeMinor grid cell size in pixels.40
colorMinor grid line color, including alpha."#FFFFFF14"
major_everyDraw a stronger line every N cells.4
major_colorMajor grid line color, including alpha."#FFFFFF26"

Examples

Clean Theme Showcase

Preview the theme without optional widgets:

veila preview \
  --config="$HOME/.config/veila/config.toml" \
  --preview-png=/tmp/veila-clean.png \
  --preview-size=1920x1080 \
  --preview-hide-widgets \
  --preview-time=08:54

Full Widget Demo

Add mock weather, battery, and media data:

veila preview \
  --config="$HOME/.config/veila/config.toml" \
  --preview-png=/tmp/veila-widgets.png \
  --preview-size=1920x1080 \
  --preview-time=21:54 \
  --preview-weather-location="Tokyo" \
  --preview-weather-condition=rain \
  --preview-weather-temperature=7 \
  --preview-battery-percent=84 \
  --preview-title="Born To Be Yours" \
  --preview-artist="Kygo, Imagine Dragons" \
  --preview-artwork="$HOME/Pictures/kygo.jpg"

On this page