sharkdp--bat/tests/syntax-tests/highlighted/Manpage/uwsm-0.26.3.man

UWSM(1)                                 General Commands Manual                                UWSM(1)

NAME
       UWSM - Universal Wayland Session Manager.

SYNOPSIS
       uwsm [-h|-v] {subcommand} [options ...]

DESCRIPTION
       Launches arbitrary wayland compositor via a set of systemd user units to provide graphical user
       session  with  environment  management, XDG autostart support, clean shutdown. Provides helpers
       for launching applications as scopes or services.

SUBCOMMANDS
       select     Select default compositor Entry.
       start      Start compositor and graphical session.
       finalize   Send compositor-set variables and unit startup notification to systemd user manager.
       stop       Stop graphical session and compositor.
       app        Application unit launcher (with Desktop Entry support).
       check      Perform state checks (for scripting and info).
       aux        Technical functions for use inside units.

       See corresponding SUBCOMMANDS subsections below for further info.

       Help for each subcommand is accessible by running "uwsm {subcommand} -h".

CONFIGURATION
   Files
       In XDG config hierarchy:
       uwsm/env
       uwsm/env.d/*
       uwsm/env-${compositor}
       uwsm/env-${compositor}.d/*   Environment (shell) to  be  sourced  for  the  graphical  session.
                                    Sourced from directories of increasing priority, in each directory
                                    common  file is sourced first, then suffixed files in the order of
                                    items listed in XDG_CURRENT_SESSION var (lowercased).
       uwsm/default-id              Stores Desktop Entry ID of default compositor.

       Fallback is also extended into the system part of XDG data hierarchy, this can be used for dis‐
       tro level defaults.

   Environment vars
       UWSM_UNIT_RUNG                  (run|home)
                                       Which rung of systemd/user/ hierarchy to manage generated  unit
                                       and drop-in files in: $XDG_RUNTIME_DIR or $XDG_CONFIG_HOME.
       UWSM_TWEAKS                     (boolean value)
                                       Set  to  False  to  remove  and not generate tweak drop-ins for
                                       other software.
       UWSM_FINALIZE_VARNAMES          (whitespace-separated names of env vars)
                                       Additional variables for "uwsm finalize".
       UWSM_WAIT_VARNAMES              (whitespace-separated names of env vars)
                                       Variables to wait for in activation environment before proceed‐
                                       ing to graphical session (in addition to WAYLAND_DISPLAY).
       UWSM_WAIT_VARNAMES_TIMEOUT      (int value)
                                       Seconds to wait for variables to appear in activation  environ‐
                                       ment. Essentially, startup timeout (default: 10).
       UWSM_WAIT_VARNAMES_SETTLETIME   (float value)
                                       Seconds  to  pause  after all expected vars found in activation
                                       environment (default: 0.2).
       UWSM_APP_UNIT_TYPE              (scope|service)
                                       Default unit type for launching apps (default: scope).
       UWSM_SILENT_START               (int or boolean value)
                                       True or 1 to inhibit stdout messages from "uwsm  start".  2  to
                                       also inhibit warnings.
       DEBUG                           (int or boolean value)
                                       True or positive number to dump debug info to stderr.

OPERATION OVERVIEW
   Login Sequence Integration
       uwsm  can  be  launched  by using conditional exec in shell profile to replace login shell (see
       Shell Profile Integration section).

       Alternatively "uwsm start ..." command can be put into wayland session's Desktop  Entry  to  be
       launched by a display manager (see Use Inside Desktop Entry section).

   Compositor Selection
       uwsm  can  run arbitrary compositor command line or a Desktop Entry by ID (specifying Action ID
       is also supported).

       Desktop Entry can also be selected via a whiptail menu (see select subcommand section).

   Startup
       See start subcommand section for command syntax.

       UWSM uses a set of units bound to standard user session targets:

       •   wayland-session-pre@.target (bound to graphical-session-pre.target)
           •   wayland-wm-env@.service (environment preloader service)
       •   wayland-session@.target (bound to graphical-session.target)
           •   wayland-wm@.service (service for the selected compositor)
       •   wayland-session-xdg-autostart@.target (bound to xdg-desktop-autostart.target)
       •   wayland-session-envelope@.target (lives through entire lifecycle)
       •   wayland-session-shutdown.target (conflicts with targets above for shutdown)
       •   wayland-session-bindpid@.service (PID-tracking session killswitch)
       •   wayland-session-waitenv.service (delays graphical session until vars appear)

       Compositor ID (Desktop Entry ID or executable name) becomes the  specifier  for  all  templated
       units.

       At  the  stage of graphical-session-pre.target, the environment saved from "uwsm start" context
       is loaded (or POSIX shell profile is sourced), uwsm environment files are sourced. The delta is
       exported to the systemd and D-Bus activation environments by the environment preloader  service
       and  is  marked  for  cleanup  at  shutdown  stage. Preloader shell context for convenience has
       IN_UWSM_ENV_PRELOADER var set to true.

       At the stage  of  graphical-session.target  (before  it)  the  main  compositor  unit  wayland-
       wm@${ID}.service and wayland-session-waitenv.service are started.

       Compositor should at least put WAYLAND_DISPLAY variable to systemd activation environment. This
       will  trigger  uwsm's automatic finalization logic. Without WAYLAND_DISPLAY in activation envi‐
       ronment startup will timeout in 10 seconds.

       Manual finalization is possible by running "uwsm finalize" (see finalize  subcommand  section),
       also  in  combination  with  tweaking UWSM_WAIT_VARNAMES and UWSM_WAIT_VARNAMES_SETTLETIME vars
       (see Environment vars section).

       Successful activation of compositor unit and existence of WAYLAND_DISPLAY in  activation  envi‐
       ronment will allow graphical-session.target to be declared reached.

       Finally, xdg-desktop-autostart.target is activated.

   Inside session
       It  is  highly recommended to configure the compositor or app launcher to launch apps as scopes
       or services in special user session slices (app.slice, background.slice,  session.slice).  uwsm
       provides custom nested slices for apps to live in and be terminated on session end:
       •   app-graphical.slice
       •   background-graphical.slice
       •   session-graphical.slice

       A  helper app subcommand is provided to handle all the systemd-run invocations for you (see app
       subcommand section).

       The compositor is launched in session.slice by default (as recommended by systemd.special(7)).

   Shutdown
       Can be initiated by either:
       •   running uwsm stop
       •   stopping wayland-wm@*.service or wayland-session-envelope@*.target
       •   starting wayland-session-shutdown.target

       Systemd stops all user units in reverse, as it usually does. During deactivation of  graphical-
       session-pre.target,  the environment preloader service cleans activation environments by unset‐
       ting all variables that were marked for removal during startup and finalization stages.

       Do not use compositor's native exit mechanism or kill its process directly.

SUBCOMMANDS
   select
       Selects default wayland session compositor Desktop Entry.

           uwsm select

       Invokes a whiptail menu to select default session among Desktop Entries in wayland-sessions XDG
       data hierarchy. Writes to ${XDG_CONFIG_HOME}/uwsm/default-id. Nothing else is done.  Returns  1
       if selection is cancelled. Can be used for scripting launch condition in shell profile.

   check
       Performs tests, returns 0 on success, 1 on failure.

       is-active:

           uwsm check is-active [-h] [-v] [compositor]

           -v           show additional info
           compositor   check for specific compositor

       Checks  if  unit of specific compositor or graphical-session*.target in general is in active or
       activating state.

       may-start:

           uwsm check may-start [-h] [-g [S]] [-v|-q] [N ...]

           N ...   allowed VT numbers (default: 1)
           -g S    wait S seconds for graphical.target in queue  (default:  60;  0  or  less  disables
                   check).
           -i      do not check for login shell
           -r      do not check for local session (allow remote session)
           -v      show all failed tests
           -q      be quiet

       Checks whether it is OK to launch a wayland session via the following conditions:
       •   DBUS_SESSION_BUS_ADDRESS is set
       •   Running from login shell
       •   System is at graphical.target
       •   User graphical-session*.target units are not yet active
       •   Foreground VT is among allowed (default: 1)
       •   Login session's VT is matching

   start
       Generates units for given compositor command line or Desktop Entry and starts them.

           uwsm  start  [-h]  [-D  name[:name...]] [-a|-e] [-N Name] [-C Comment] [-U {run|home}] [-t]
           [-o] [-n] -- compositor [args ...]

           -F                  Hardcode mode, always write command line to unit drop-ins and use  full
                               paths.
           -D name[:name...]   Names to fill XDG_CURRENT_DESKTOP with (:-separated). Existing var con‐
                               tent is a starting point if no active session is running.
           -a                  Append desktop names set by -D to other sources (default).
           -e                  Use desktop names set by -D exclusively, discard other sources.
           -N Name             Fancy name for compositor (filled from Desktop Entry by default).
           -C Comment          Fancy  description  for  compositor  (filled  from Desktop Entry by de‐
                               fault).
           -U {run|home}       Select  rung  for  generated  unit  files:  run:  $XDG_RUNTIME_DIR/sys‐
                               temd/user  (default), or home: $XDG_CONFIG_HOME/systemd/user. Permanent
                               destination will save some time by removing need for reloading systemd.
                               Managed files from other rung will  be  removed.  Can  be  preset  with
                               UWSM_UNIT_RUNG environment var.
           -t                  Do  not  generate  (and  remove)  tweak  unit files. Can be preset with
                               UWSM_TWEAKS=false environment var.
           -T                  Generate tweak unit files for other software. This is default behavior.
           -g S                Wait for S seconds for system graphical.target in  queue  and  warn  if
                               timed out or not in queue (default: 60, negative to disable).
           -G S                Wait  for  S  seconds for system graphical.target in queue and abort if
                               timed out or not in queue (overrides -g, default: -1, (disabled)).
           -o                  Only generate units, but do not start.
           -n                  Dry run, do not write or start anything.

       The first argument of the compositor command line acts as an ID and should be either one of:
       •   Executable name
       •   Desktop Entry ID (optionally with ":"-delimited action ID)
       •   Special value:
           •   select - invoke menu to select compositor.
           •   default - run previously selected compositor (or select if no selection was saved).

       If given as path, hardcode mode will be used implicitly.

       Always use "--" to disambiguate dashed arguments intended for compositor itself.

       After units are (re)generated, wayland-session-bindpid@${PID}.service is started, to track  the
       PID  of  invoking  uwsm, then uwsm process replaces itself with systemctl execution that starts
       wayland-wm@${ID}.service and waits for it to finish.

       In order to complete the startup sequence, the compositor has to put WAYLAND_DISPLAY  into  the
       systemd  activation environment. This can be done explicitly by making compositor run "uwsm fi‐
       nalize" command (see the next subsection).

   finalize
       For running by a compositor on startup.

           uwsm finalize [-h] [VAR_NAME ...]

       Exports WAYLAND_DISPLAY, DISPLAY and any defined vars mentioned by names  in  arguments  or  in
       UWSM_FINALIZE_VARNAMES variable (whitespace-separated). Then sends startup notification for the
       unit to systemd user manager.

       This  is required if compositor itself does not put WAYLAND_DISPLAY to systemd activation envi‐
       ronment, otherwise wayland-session@.service unit or a dedicated wayland-session-waitenv.service
       unit will terminate due to startup timeout.

       UWSM_FINALIZE_VARNAMES variable can be prefilled by plugins.

       Direct assignment as VAR_NAME=value is also possible, but recommended only for  creating  flags
       for UWSM_WAIT_VARNAMES mechanism.

   stop
       Stops compositor and optionally removes generated units.

           uwsm stop [-h] [-r [compositor] [-U {run|home}] [-n]

           -r [compositor]   Also remove units (all or only compositor-specific).
           -U {run|home}     Select  rung for generated unit files: run: $XDG_RUNTIME_DIR/systemd/user
                             (default), or home: $XDG_CONFIG_HOME/systemd/user. Permanent  destination
                             will save some time by removing need for reloading systemd. Managed files
                             from  other rung will be removed. Can be preset with UWSM_UNIT_RUNG envi‐
                             ronment var.
           -n                Dry run, do not stop or remove anything.

   app
       Application-to-unit launcher with Desktop Entry support.

           uwsm app [-h] [-s {a,b,s,custom.slice}] [-t {scope,service}] [-a app_name]  [-u  unit_name]
           [-d unit_description] [-S ] [-T] -- application [args ...]

           -s {a,b,s,custom.slice}   Slice selector (default: a):
                                        a - app-graphical.slice
                                        b - background-graphical.slice
                                        s - session-graphical.slice
                                        any slice by full name
           -t {scope,service}        Type  of  unit  to  launch  (default:  scope,  can  be  preset by
                                     UWSM_APP_UNIT_TYPE env var).
           -a app_name               Override app name (a substring in unit name).
           -u unit_name              Override the whole autogenerated unit name.
           -d unit_description       Unit Description.
           -p Property=value         Set additional unit property (option is repeatable).
           -S {out,err,both}         Silence stdout, stderr, or both.
           -T                        Launch app in a terminal. Allows command  to  be  empty  to  just
                                     launch a terminal.

       Application  can  be  provided as a command with optional arguments, or a Desktop Entry ID, op‐
       tionally suffixed with ":"-delimited Action ID. If Desktop Entry is being  launched,  arguments
       should be compatible with it.

       Always use "--" to disambiguate dashed arguments intended for application itself.

   aux
       For use in systemd user services. Can only be called by systemd user manager.

       prepare-env   Prepares  environment  (for  use in ExecStart in wayland-wm-env@.service bound to
                     wayland-session-pre@.target).
       cleanup-env   Cleans up environment (for use ExecStop in in  wayland-wm-env@.service  bound  to
                     wayland-session-pre@.target).
       exec          Executes a command with arguments or a desktop entry (for use in Exec in wayland-
                     wm@.service bound to wayland-session@.target).
       app-daemon    Daemon for faster app argument generation, used by uwsm-app client.

APP DAEMON
       Provided as wayland-wm-app-daemon.service to be started on-demand.

       Daemon  receives app arguments from ${XDG_RUNTIME_DIR}/uwsm-app-daemon-in pipe. Resulting argu‐
       ments are formatted as shell code and written to ${XDG_RUNTIME_DIR}/uwsm-app-daemon-out pipe.

       Arguments are expected to be \0-delimited, leading \0 are stripped. One command is received per
       write+close.

       The first argument determines the behavior:

       •   app  the rest is processed the same as in "uwsm app"
       •   ping just "pong" is returnedn
       •   stop daemon is stoppedn

       Single commands are prepended with exec, iterated commands are assembled with trailing &  each,
       followed by wait.

       The  purpose  of  all this is to skip all the expensive Python startup and import routines that
       slow things down every time "uwsm app" is called. Instead the daemon does it once and then lis‐
       tens for requests, while a simple shell script may dump arguments to one pipe and run the  code
       received from another via eval, which is much faster.

       The simplest script is:

                #!/bin/sh
                printf '0%s' app "$@" > "${XDG_RUNTIME_DIR}/uwsm-app-daemon-in"
                IFS='' read -r cmd < "${XDG_RUNTIME_DIR}/uwsm-app-daemon-out"
                eval "$cmd"

       Provided  uwsm-app  client  script is a bit smarter: it can start the daemon, applies timeouts,
       and supports newlines in returned args.

SHELL PROFILE INTEGRATION
       To launch uwsm automatically on login, add one of constructs below (or similar) to  shell  pro‐
       file.

       This asks to select a compositor (or refuse and continue with login shell) when logged in on VT
       1:

                if uwsm check may-start && uwsm select; then
                     exec systemd-cat -t uwsm_start uwsm start default
                fi

       This just starts a specific compositor depending on foreground VT:

                if uwsm check may-start 1; then
                     exec systemd-cat -t uwsm_start uwsm start sway.desktop
                elif uwsm check may-start 2; then
                     exec systemd-cat -t uwsm_start uwsm start labwc.desktop
                fi

       Using  "uwsm  check  may-start"  as  a  condition  is essential, not only to prevent accidental
       startup attempts where they are not expected, but also since startup may involve sourcing shell
       profile, which might lead to nasty loops.

       See check subcommand section for info on may-start checker.

       exec allows uwsm to replace login shell in order to properly bind to user  session  and  handle
       session termination.

       "systemd-cat  -t uwsm_start" (optional) executes the command given to it (uwsm) with its stdout
       and stderr connected to the systemd journal, tagged with identifier "uwsm_start". See  systemd-
       cat(1) for more options.

USE INSIDE DESKTOP ENTRY
       To  launch  uwsm from a display/login manager, "uwsm start" can be used inside Desktop Entries.
       Example /usr/local/share/wayland-sessions/my-compositor.desktop:

                [Desktop Entry]
                Name=My compositor (with UWSM)
                Comment=My cool compositor
                Exec=uwsm start -N "My compositor" -D mycompositor -C "My cool compositor" mywm
                DesktopNames=mycompositor
                Type=Application

       Things to keep in mind:

       •   For consistency, command line arguments should mirror the keys of the entry
       •   Command in Exec= should start with "uwsm start"
       •   It should not point to itself (as a combination of Desktop Entry ID and Action ID)
       •   It should not point to a Desktop Entry ID and Action ID that also uses ‘uwsm‘

       Potentially such entries may be found and used by uwsm itself, i.e. in shell  profile  integra‐
       tion  situation,  or  when  launched manually. Following the principles above ensures uwsm will
       properly recognize itself and parse requested arguments inside the entry without any  side  ef‐
       fects.

SEE ALSO
       uwsm-plugins(3), systemd-run(1), systemd-cat(1), systemd.special(7)

                                              2026-02-14                                       UWSM(1)