Lock Control

For normal locking:

veila lock

When you need the script to continue only once the actual secure session-locking surfaces become active, use the following:

veila lock --wait-ready

This command will block until the secure lock becomes ready and then return:

lock_ready=true
already_active=false

The veila lock should be used for manually bound keys. The veila lock --wait-ready should be used for Hypridle, suspending scripts, DPMS callbacks, etc.

hypridle example

general {
    lock_cmd = veila lock --wait-ready              # veila screen lock
    before_sleep_cmd = veila lock --wait-ready      # lock before suspend
    after_sleep_cmd = hyprctl dispatch dpms on      # wake display after sleep
    inhibit_sleep = 3
}

# Dim the screen first (optional)
listener {
    timeout = 150                                   # 2.5 minutes
    on-timeout = brightnessctl -s set 10%           # set monitor backlight to 10%
    on-resume = brightnessctl -r                    # restore monitor backlight
}

# Lock the screen (Visible)
listener {
    timeout = 300                                   # 5 minutes
    on-timeout = veila lock --wait-ready            # lock screen (stays visible)
}

# Turn off the screen (Black out)
listener {
    timeout = 600                                   # 10 minutes (5 mins after locking)
    on-timeout = hyprctl dispatch dpms off          # turn off display
    on-resume = hyprctl dispatch dpms on            # turn on display
}

Built-in idle monitor

Veila can also watch compositor-reported idle time directly:

veila idle

By default, this asks the running daemon to lock after 5 minutes of idle time. To choose another timeout:

veila idle --lock-after=600

The idle monitor uses the Wayland ext-idle-notify-v1 protocol and keeps running in the foreground. Start veilad separately before running it.

To also lock before system sleep:

veila idle --lock-before-sleep

This subscribes to logind PrepareForSleep and holds a sleep delay inhibitor while preparing the lock. You can combine both options:

veila idle --lock-after=600 --lock-before-sleep

Packages also install veila-idle.service, which runs:

veila idle --lock-after=300 --lock-before-sleep

Customize the packaged service without editing the unit file by creating ~/.config/veila/idle.env:

VEILA_IDLE_LOCK_AFTER=600
VEILA_IDLE_SLEEP_FLAG=--lock-before-sleep

Then restart the service:

systemctl --user restart veila-idle.service

To disable lock-before-sleep while keeping idle locking, set:

VEILA_IDLE_SLEEP_FLAG=

Enable it after veilad.service when your user service environment has the Wayland session variables:

systemctl --user enable --now veilad.service
systemctl --user enable --now veila-idle.service

Emergency unlock prompt

Veila has a built-in emergency unlock prompt for cases where the rich lock scene cannot be prepared safely. It still runs on the secure ext-session-lock-v1 surfaces and uses the same daemon/PAM authentication flow; only the presentation is simplified.

To test it intentionally:

veila lock --force-emergency-ui --wait-ready

You should see a minimal password prompt

Latency report

To inspect lock activation timing, run:

veila lock --latency-report --wait-ready

The command prints a compact timing report after the secure lock is ready. It includes daemon setup, curtain spawn, Wayland startup, first surface configure, first frame, session-lock confirmation, and readiness timings. Password text and PAM responses are never included.

For deeper local profiling, use:

veila lock --latency-report=verbose --wait-ready

Verbose mode keeps the compact millisecond fields and adds microsecond fields plus derived startup gaps such as first-frame to session-lock confirmation.