.\" Generated by scdoc 1.11.5
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "UWSM" "1" "2026\-08\-24"
.PP
.SH NAME
.PP
\fBUWSM\fR \- Universal Wayland Session Manager.\&
.PP
.SH SYNOPSIS
.PP
\fBuwsm\fR [\-h|\-v] {\fIsubcommand\fR} [\fIoptions\fR .\&.\&.\&]
.PP
.SH DESCRIPTION
.PP
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.\&
.PP
.SH SUBCOMMANDS
.PP
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fBselect\fR
T}	T{
Select default compositor Entry.\&
T}
T{
\fBstart\fR
T}	T{
Start compositor and graphical session.\&
T}
T{
\fBfinalize\fR
T}	T{
Send compositor\-set variables and unit startup notification to systemd user manager.\&
T}
T{
\fBstop\fR
T}	T{
Stop graphical session and compositor.\&
T}
T{
\fBapp\fR
T}	T{
Application unit launcher (with Desktop Entry support).\&
T}
T{
\fBcheck\fR
T}	T{
Perform state checks (for scripting and info).\&
T}
T{
\fBaux\fR
T}	T{
Technical functions for use inside units.\&
T}
.TE
.sp 1
See corresponding \fISUBCOMMANDS\fR subsections below for further info.\&
.PP
Help for each subcommand is accessible by running "\fBuwsm\fR {\fIsubcommand\fR} \fB\-h\fR".\&
.PP
.SH CONFIGURATION
.PP
.SS Files
.PP
In XDG config hierarchy:
.TS
l lx
l lx
l lx
l lx
l lx.
T{
\fBuwsm/env\fR
T}	T{

T}
T{
\fBuwsm/env.\&d/\fR*
T}	T{

T}
T{
\fBuwsm/env\-\fR\fI${compositor}\fR
T}	T{

T}
T{
\fBuwsm/env\-\fR\fI${compositor}\fR\fB.\&d/\fR*
T}	T{
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 \fBXDG_CURRENT_SESSION\fR var (lowercased).\&
T}
T{
\fBuwsm/default\-id\fR
T}	T{
Stores Desktop Entry ID of default compositor.\&
T}
.TE
.sp 1
Fallback is also extended into the system part of XDG data hierarchy, this can
be used for distro level defaults.\&
.PP
.SS Environment vars
.PP
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fBUWSM_UNIT_RUNG\fR
T}	T{
(\fBrun\fR|\fBhome\fR)
T}
T{

T}	T{
Which rung of systemd/user/ hierarchy to manage generated unit and drop\-in files in: $XDG_RUNTIME_DIR or $XDG_CONFIG_HOME.\&
T}
T{
\fBUWSM_TWEAKS\fR
T}	T{
(boolean value)
T}
T{

T}	T{
Set to \fIFalse\fR to remove and not generate tweak drop\-ins for other software.\&
T}
T{
\fBUWSM_FINALIZE_VARNAMES\fR
T}	T{
(whitespace\-separated names of env vars)
T}
T{

T}	T{
Additional variables for "\fBuwsm finalize\fR".\&
T}
T{
\fBUWSM_WAIT_VARNAMES\fR
T}	T{
(whitespace\-separated names of env vars)
T}
T{

T}	T{
Variables to wait for in activation environment before proceeding to graphical session (in addition to \fBWAYLAND_DISPLAY\fR).\&
T}
T{
\fBUWSM_WAIT_VARNAMES_TIMEOUT\fR
T}	T{
(int value)
T}
T{

T}	T{
Seconds to wait for variables to appear in activation environment.\& Essentially, startup timeout (default: 10).\&
T}
T{
\fBUWSM_WAIT_VARNAMES_SETTLETIME\fR
T}	T{
(float value)
T}
T{

T}	T{
Seconds to pause after all expected vars found in activation environment (default: 0.\&2).\&
T}
T{
\fBUWSM_APP_UNIT_TYPE\fR
T}	T{
(\fBscope\fR|\fBservice\fR)
T}
T{

T}	T{
Default unit type for launching apps (default: \fBscope\fR).\&
T}
T{
\fBUWSM_SILENT_START\fR
T}	T{
(int or boolean value)
T}
T{

T}	T{
\fITrue\fR or \fB1\fR to inhibit stdout messages from "\fBuwsm start\fR".\& \fB2\fR to also inhibit warnings.\&
T}
T{
\fBDEBUG\fR
T}	T{
(int or boolean value)
T}
T{

T}	T{
\fITrue\fR or positive number to dump debug info to stderr.\&
T}
.TE
.sp 1
.SH OPERATION OVERVIEW
.PP
.SS Login Sequence Integration
.PP
\fBuwsm\fR can be launched by using conditional \fBexec\fR in shell profile to replace
login shell (see \fIShell Profile Integration\fR section).\&
.PP
Alternatively "\fBuwsm start\fR .\&.\&.\&" command can be put into wayland session'\&s
Desktop Entry to be launched by a display manager (see \fIUse Inside Desktop
Entry\fR section).\&
.PP
.SS Compositor Selection
.PP
\fBuwsm\fR can run arbitrary compositor command line or a Desktop Entry by ID
(specifying Action ID is also supported).\&
.PP
Desktop Entry can also be selected via a \fBwhiptail\fR menu (see \fIselect\fR
subcommand section).\&
.PP
.SS Startup
.PP
See \fIstart\fR subcommand section for command syntax.\&
.PP
UWSM uses a set of units bound to standard user session targets:
.PP
.PD 0
.IP \(bu 4
\fBwayland\-session\-pre@.\&target\fR (bound to \fBgraphical\-session\-pre.\&target\fR)
.RS 4
.IP \(bu 4
\fBwayland\-wm\-env@.\&service\fR (environment preloader service)
.RE
.IP \(bu 4
\fBwayland\-session@.\&target\fR (bound to \fBgraphical\-session.\&target\fR)
.RS 4
.IP \(bu 4
\fBwayland\-wm@.\&service\fR (service for the selected compositor)
.RE
.IP \(bu 4
\fBwayland\-session\-xdg\-autostart@.\&target\fR (bound to
\fBxdg\-desktop\-autostart.\&target\fR)
.IP \(bu 4
\fBwayland\-session\-envelope@.\&target\fR (lives through entire lifecycle)
.IP \(bu 4
\fBwayland\-session\-shutdown.\&target\fR (conflicts with targets above for shutdown)
.IP \(bu 4
\fBwayland\-session\-bindpid@.\&service\fR (PID\-tracking session killswitch)
.IP \(bu 4
\fBwayland\-session\-waitenv.\&service\fR (delays graphical session until vars appear)
.PD
.PP
Compositor ID (Desktop Entry ID or executable name) becomes the specifier
for all templated units.\&
.PP
At the stage of \fBgraphical\-session\-pre.\&target\fR, the environment saved from
"\fBuwsm start\fR" context is loaded (or POSIX shell profile is sourced), uwsm
environment \fIfiles\fR 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
\fBIN_UWSM_ENV_PRELOADER\fR var set to \fBtrue\fR.\&
.PP
At the stage of \fBgraphical\-session.\&target\fR (before it) the main compositor unit
\fBwayland\-wm@\fR\fI${ID}\fR\fB.\&service\fR and \fBwayland\-session\-waitenv.\&service\fR are
started.\&
.PP
Compositor should at least put \fBWAYLAND_DISPLAY\fR variable to systemd activation
environment.\& This will trigger uwsm'\&s automatic finalization logic.\& Without
\fBWAYLAND_DISPLAY\fR in activation environment startup will timeout in 10 seconds.\&
.PP
Manual finalization is possible by running "\fBuwsm finalize\fR" (see \fIfinalize\fR
subcommand section), also in combination with tweaking \fBUWSM_WAIT_VARNAMES\fR
and \fBUWSM_WAIT_VARNAMES_SETTLETIME\fR vars (see \fIEnvironment vars\fR section).\&
.PP
Successful activation of compositor unit and existence of \fBWAYLAND_DISPLAY\fR
in activation environment will allow \fBgraphical\-session.\&target\fR to be declared
reached.\&
.PP
Finally, \fBxdg\-desktop\-autostart.\&target\fR is activated.\&
.PP
.SS Inside session
.PP
It is highly recommended to configure the compositor or app launcher to launch
apps as scopes or services in special user session slices (\fBapp.\&slice\fR,
\fBbackground.\&slice\fR, \fBsession.\&slice\fR).\& \fBuwsm\fR provides custom nested slices for
apps to live in and be terminated on session end:
.PD 0
.IP \(bu 4
\fBapp\-graphical.\&slice\fR
.IP \(bu 4
\fBbackground\-graphical.\&slice\fR
.IP \(bu 4
\fBsession\-graphical.\&slice\fR
.PD
.PP
A helper \fBapp\fR subcommand is provided to handle all the systemd\-run invocations
for you (see \fIapp\fR subcommand section).\&
.PP
The compositor is launched in \fBsession.\&slice\fR by default (as recommended by
\fBsystemd.\&special\fR(7)).\&
.PP
.SS Shutdown
.PP
Can be initiated by either:
.PD 0
.IP \(bu 4
running \fBuwsm stop\fR
.IP \(bu 4
stopping \fBwayland\-wm@*.\&service\fR or \fBwayland\-session\-envelope@*.\&target\fR
.IP \(bu 4
starting \fBwayland\-session\-shutdown.\&target\fR
.PD
.PP
Systemd stops all user units in reverse, as it usually does.\& During deactivation
of \fBgraphical\-session\-pre.\&target\fR, the environment preloader service cleans
activation environments by unsetting all variables that were marked for removal
during startup and finalization stages.\&
.PP
Do not use compositor'\&s native exit mechanism or kill its process directly.\&
.PP
.SH SUBCOMMANDS
.PP
.SS select
.PP
Selects default wayland session compositor Desktop Entry.\&
.PP
.RS 4
\fBuwsm\fR select
.PP
.RE
Invokes a whiptail menu to select default session among Desktop Entries in
\fBwayland\-sessions\fR XDG data hierarchy.\& Writes to
\fB${XDG_CONFIG_HOME}/uwsm/default\-id\fR.\& Nothing else is done.\& Returns \fB1\fR if
selection is cancelled.\& Can be used for scripting launch condition in shell
profile.\&
.PP
.SS check
.PP
Performs tests, returns \fB0\fR on success, \fB1\fR on failure.\&
.PP
\fBis\-active\fR:
.PP
.RS 4
\fBuwsm\fR check is\-active [\-h] [\-v] [\fIcompositor\fR]
.PP
.RE
.TS
l lx
l lx.
T{
    \fB\-v\fR
T}	T{
show additional info
T}
T{
    \fIcompositor\fR
T}	T{
check for specific compositor
T}
.TE
.sp 1
.PP
Checks if unit of specific \fBcompositor\fR or \fBgraphical\-session*.\&target\fR in
general is in active or activating state.\&
.PP
\fBmay\-start\fR:
.PP
.RS 4
\fBuwsm\fR check may\-start [\-h] [\-g [\fIS\fR]] [\-v|\-q] [\fIN\fR .\&.\&.\&]
.PP
.RE
.TS
l lx
l lx
l lx
l lx
l lx
l lx.
T{
    \fIN\fR .\&.\&.\&
T}	T{
allowed VT numbers (default: 1)
T}
T{
    \fB\-g\fR \fIS\fR
T}	T{
wait \fIS\fR seconds for graphical.\&target in queue (default: 60; 0 or less disables check).\&
T}
T{
    \fB\-i\fR
T}	T{
do not check for login shell
T}
T{
    \fB\-r\fR
T}	T{
do not check for local session (allow remote session)
T}
T{
    \fB\-v\fR
T}	T{
show all failed tests
T}
T{
    \fB\-q\fR
T}	T{
be quiet
T}
.TE
.sp 1
.PP
Checks whether it is OK to launch a wayland session via the following conditions:
.PD 0
.IP \(bu 4
\fBDBUS_SESSION_BUS_ADDRESS\fR is set
.IP \(bu 4
Running from login shell
.IP \(bu 4
System is at \fBgraphical.\&target\fR
.IP \(bu 4
User \fBgraphical\-session*.\&target\fR units are not yet active
.IP \(bu 4
Foreground VT is among allowed (default: 1)
.IP \(bu 4
Login session'\&s VT is matching
.PD
.PP
.SS start
.PP
Generates units for given compositor command line or Desktop Entry and starts
them.\&
.PP
.RS 4
\fBuwsm\fR start [\-h] [\-D \fIname\fR[:\fIname\fR.\&.\&.\&]] [\-a|\-e] [\-N \fIName\fR] [\-C \fIComment\fR]
[\-U {run|home}] [\-t] [\-o] [\-n] \-\- \fIcompositor\fR [\fIargs\fR .\&.\&.\&]
.PP
.RE
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
    \fB\-F\fR
T}	T{
Hardcode mode, always write command line to unit drop\-ins and use full paths.\&
T}
T{
    \fB\-D\fR \fIname\fR[:\fIname\fR.\&.\&.\&]
T}	T{
Names to fill \fBXDG_CURRENT_DESKTOP\fR with (:\-separated).\& Existing var content is a starting point if no active session is running.\&
T}
T{
    \fB\-a\fR
T}	T{
Append desktop names set by \-D to other sources (default).\&
T}
T{
    \fB\-e\fR
T}	T{
Use desktop names set by \-D exclusively, discard other sources.\&
T}
T{
    \fB\-N\fR \fIName\fR
T}	T{
Fancy name for compositor (filled from Desktop Entry by default).\&
T}
T{
    \fB\-C\fR \fIComment\fR
T}	T{
Fancy description for compositor (filled from Desktop Entry by default).\&
T}
T{
    \fB\-U\fR {\fBrun\fR|\fBhome\fR}
T}	T{
Select rung for generated unit files: \fBrun\fR: $XDG_RUNTIME_DIR/systemd/user (default), or \fBhome\fR: $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 \fBUWSM_UNIT_RUNG\fR environment var.\&
T}
T{
    \fB\-t\fR
T}	T{
Do not generate (and remove) tweak unit files.\& Can be preset with \fBUWSM_TWEAKS=false\fR environment var.\&
T}
T{
    \fB\-T\fR
T}	T{
Generate tweak unit files for other software.\& This is default behavior.\&
T}
T{
    \fB\-g\fR \fIS\fR
T}	T{
Wait for S seconds for system graphical.\&target in queue and warn if timed out or not in queue (default: 60, negative to disable).\&
T}
T{
    \fB\-G\fR \fIS\fR
T}	T{
Wait for S seconds for system graphical.\&target in queue and abort if timed out or not in queue (overrides \-g, default: \-1, (disabled)).\&
T}
T{
    \fB\-o\fR
T}	T{
Only generate units, but do not start.\&
T}
T{
    \fB\-n\fR
T}	T{
Dry run, do not write or start anything.\&
T}
.TE
.sp 1
The first argument of the compositor command line acts as an ID and should be
either one of:
.PD 0
.IP \(bu 4
Executable name
.IP \(bu 4
Desktop Entry ID (optionally with "\fB:\fR"\-delimited action ID)
.IP \(bu 4
Special value:
.RS 4
.IP \(bu 4
\fBselect\fR \- invoke menu to select compositor.\&
.IP \(bu 4
\fBdefault\fR \- run previously selected compositor (or select if no
selection was saved).\&
.PD
.PP
.RE
If given as path, hardcode mode will be used implicitly.\&
.PP
Always use "\fB\-\-\fR" to disambiguate dashed arguments intended for compositor
itself.\&
.PP
After units are (re)generated, \fBwayland\-session\-bindpid@\fR\fI${PID}\fR\fB.\&service\fR is
started, to track the PID of invoking \fBuwsm\fR, then \fBuwsm\fR process replaces
itself with \fBsystemctl\fR execution that starts \fBwayland\-wm@\fR\fI${ID}\fR\fB.\&service\fR
and waits for it to finish.\&
.PP
In order to complete the startup sequence, the compositor has to put
\fBWAYLAND_DISPLAY\fR into the systemd activation environment.\& This can be done
explicitly by making compositor run "\fBuwsm finalize\fR" command (see the next
subsection).\&
.PP
.SS finalize
.PP
For running by a compositor on startup.\&
.PP
.RS 4
\fBuwsm\fR finalize [\-h] [\fIVAR_NAME\fR .\&.\&.\&]
.PP
.RE
Exports \fBWAYLAND_DISPLAY\fR, \fBDISPLAY\fR and any defined vars mentioned by names
in arguments or in \fBUWSM_FINALIZE_VARNAMES\fR variable (whitespace\-separated).\&
Then sends startup notification for the unit to systemd user manager.\&
.PP
\fBThis is required\fR if compositor itself does not put \fBWAYLAND_DISPLAY\fR to
systemd activation environment, otherwise \fBwayland\-session@.\&service\fR unit
or a dedicated \fBwayland\-session\-waitenv.\&service\fR unit will terminate due to
startup timeout.\&
.PP
\fBUWSM_FINALIZE_VARNAMES\fR variable can be prefilled by plugins.\&
.PP
Direct assignment as \fIVAR_NAME\fR=\fIvalue\fR is also possible, but recommended only
for creating flags for \fBUWSM_WAIT_VARNAMES\fR mechanism.\&
.PP
.SS stop
.PP
Stops compositor and optionally removes generated units.\&
.PP
.RS 4
\fBuwsm\fR stop [\-h] [\-r [\fIcompositor\fR] [\-U {run|home}] [\-n]
.PP
.RE
.TS
l lx
l lx
l lx.
T{
    \fB\-r\fR [\fIcompositor\fR]
T}	T{
Also remove units (all or only \fIcompositor\fR\-specific).\&
T}
T{
    \fB\-U\fR {\fBrun\fR|\fBhome\fR}
T}	T{
Select rung for generated unit files: \fBrun\fR: $XDG_RUNTIME_DIR/systemd/user (default), or \fBhome\fR: $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 \fBUWSM_UNIT_RUNG\fR environment var.\&
T}
T{
    \fB\-n\fR
T}	T{
Dry run, do not stop or remove anything.\&
T}
.TE
.sp 1
.SS app
.PP
Application\-to\-unit launcher with Desktop Entry support.\&
.PP
.RS 4
\fBuwsm\fR app [\-h] [\-s {\fBa\fR,\fBb\fR,\fBs\fR,\fIcustom\fR.\&slice}] [\-t {scope,service}]
[\-a \fIapp_name\fR] [\-u \fIunit_name\fR] [\-d \fIunit_description\fR]
[\-S ] [\-T] \-\- \fIapplication\fR [\fIargs\fR .\&.\&.\&]
.PP
.RE
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
    \fB\-s\fR {\fBa\fR,\fBb\fR,\fBs\fR,\fIcustom\fR.\&slice}
T}	T{
Slice selector (default: \fBa\fR):
T}
T{

T}	T{
   \fBa\fR \- \fBapp\-graphical.\&slice\fR
T}
T{

T}	T{
   \fBb\fR \- \fBbackground\-graphical.\&slice\fR
T}
T{

T}	T{
   \fBs\fR \- \fBsession\-graphical.\&slice\fR
T}
T{

T}	T{
   any slice by full name
T}
T{
    \fB\-t\fR {\fBscope\fR,\fBservice\fR}
T}	T{
Type of unit to launch (default: \fBscope\fR, can be preset by \fBUWSM_APP_UNIT_TYPE\fR env var).\&
T}
T{
    \fB\-a\fR \fIapp_name\fR
T}	T{
Override app name (a substring in unit name).\&
T}
T{
    \fB\-u\fR \fIunit_name\fR
T}	T{
Override the whole autogenerated unit name.\&
T}
T{
    \fB\-d\fR \fIunit_description\fR
T}	T{
Unit Description.\&
T}
T{
    \fB\-p\fR \fIProperty\fR=\fIvalue\fR
T}	T{
Set additional unit property (option is repeatable).\&
T}
T{
    \fB\-S\fR {\fBout\fR,\fBerr\fR,\fBboth\fR}
T}	T{
Silence stdout, stderr, or both.\&
T}
T{
    \fB\-T\fR
T}	T{
Launch app in a terminal.\& Allows command to be empty to just launch a terminal.\&
T}
.TE
.sp 1
.PP
Application can be provided as a command with optional arguments, or a Desktop
Entry ID, optionally suffixed with "\fB:\fR"\-delimited Action ID.\& If Desktop Entry
is being launched, arguments should be compatible with it.\&
.PP
Always use "\fB\-\-\fR" to disambiguate dashed arguments intended for application
itself.\&
.PP
.SS aux
.PP
For use in systemd user services.\& Can only be called by systemd user manager.\&
.PP
.TS
l lx
l lx
l lx
l lx.
T{
\fBprepare\-env\fR
T}	T{
Prepares environment (for use in ExecStart in \fBwayland\-wm\-env@.\&service\fR bound to \fBwayland\-session\-pre@.\&target\fR).\&
T}
T{
\fBcleanup\-env\fR
T}	T{
Cleans up environment (for use ExecStop in in \fBwayland\-wm\-env@.\&service\fR bound to \fBwayland\-session\-pre@.\&target\fR).\&
T}
T{
\fBexec\fR
T}	T{
Executes a command with arguments or a desktop entry (for use in Exec in \fBwayland\-wm@.\&service\fR bound to \fBwayland\-session@.\&target\fR).\&
T}
T{
\fBapp\-daemon\fR
T}	T{
Daemon for faster app argument generation, used by \fBuwsm\-app\fR client.\&
T}
.TE
.sp 1
.SH APP DAEMON
.PP
Provided as \fBwayland\-wm\-app\-daemon.\&service\fR to be started on\-demand.\&
.PP
Daemon receives app arguments from \fB${XDG_RUNTIME_DIR}/uwsm\-app\-daemon\-in\fR
pipe.\&
Resulting arguments are formatted as shell code and written to
\fB${XDG_RUNTIME_DIR}/uwsm\-app\-daemon\-out\fR pipe.\&
.PP
Arguments are expected to be \fB\e0\fR\-delimited, leading \fB\e0\fR are stripped.\&
One command is received per write+close.\&
.PP
The first argument determines the behavior:
.PP
.PD 0
.IP \(bu 4
\fBapp\fR	the rest is processed the same as in "uwsm app"
.IP \(bu 4
\fBping\fR	just "pong" is returnedn
.IP \(bu 4
\fBstop\fR	daemon is stoppedn
.PD
.PP
.PP
Single commands are prepended with \fBexec\fR, iterated commands are assembled with
trailing \fB&\fR each, followed by \fBwait\fR.\&
.PP
The purpose of all this is to skip all the expensive Python startup and import
routines that slow things down every time "\fBuwsm app\fR" is called.\& Instead the
daemon does it once and then listens 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.\&
.PP
The simplest script is:
.PP
.nf
.RS 4
	#!/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"
.fi
.RE
.PP
Provided \fBuwsm\-app\fR client script is a bit smarter: it can start the daemon,
applies timeouts, and supports newlines in returned args.\&
.PP
.SH SHELL PROFILE INTEGRATION
.PP
To launch \fBuwsm\fR automatically on login, add one of constructs below (or
similar) to shell profile.\&
.PP
This asks to select a compositor (or refuse and continue with login shell)
when logged in on VT 1:
.PP
.nf
.RS 4
	if uwsm check may\-start && uwsm select; then
		exec systemd\-cat \-t uwsm_start uwsm start default
	fi
.fi
.RE
.PP
This just starts a specific compositor depending on foreground VT:
.PP
.nf
.RS 4
	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
.fi
.RE
.PP
Using "\fBuwsm check may\-start\fR" as a condition is \fBessential\fR, 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.\&
.PP
See \fIcheck\fR subcommand section for info on \fBmay\-start\fR checker.\&
.PP
\fBexec\fR allows uwsm to replace login shell in order to properly bind to user
session and handle session termination.\&
.PP
"\fBsystemd\-cat \-t uwsm_start\fR" (optional) executes the command given to it
(\fBuwsm\fR) with its stdout and stderr connected to the systemd journal, tagged
with identifier "uwsm_start".\& See \fIsystemd\-cat(1)\fR for more options.\&
.PP
.SH USE INSIDE DESKTOP ENTRY
.PP
To launch \fBuwsm\fR from a display/login manager, "\fBuwsm start\fR" can be used inside
Desktop Entries.\& Example
\fB/usr/local/share/wayland\-sessions/my\-compositor.\&desktop\fR:
.PP
.nf
.RS 4
	[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
.fi
.RE
.PP
Things to keep in mind:
.PP
.PD 0
.IP \(bu 4
For consistency, command line arguments should mirror the keys of the entry
.IP \(bu 4
Command in \fBExec=\fR should start with "\fBuwsm start\fR"
.IP \(bu 4
It should not point to itself (as a combination of Desktop Entry ID and Action
ID)
.IP \(bu 4
It should not point to a Desktop Entry ID and Action ID that also uses `uwsm`
.PD
.PP
Potentially such entries may be found and used by \fBuwsm\fR itself, i.\&e.\& in shell
profile integration situation, or when launched manually.\& Following the
principles above ensures \fBuwsm\fR will properly recognize itself and parse
requested arguments inside the entry without any side effects.\&
.PP
.SH SEE ALSO
.PP
\fBuwsm\-plugins\fR(3), \fBsystemd\-run\fR(1), \fBsystemd\-cat\fR(1), \fBsystemd.\&special\fR(7)