XDG-LAUNCH(1)

📦 version 1.12, in nixos 26.05, nixpkgs unstable

🎀 xdg-launch 🎀 — that's section 1 of the User Commands manual, bestie

okay so, real talk: this is the manual page for xdg-launch, section 1, User Commands. Let's get into it ✨

🌸 NAME 🌸

xdg-launch — an XDG compliant startup notification launcher 🚀

✨ SYNOPSIS ✨

like, here's every single way you can call her:

 xdg-launch [OPTIONS] [APPSPEC [FILE|URL]...|COMMAND]
 xdg-launch {-U|--autostart} [OPTIONS] [APPID|DESKTOP|COMMAND]
 xdg-launch {-X|--xsession}  [OPTIONS] [ACTID|DESKTOP|COMMAND]
 xdg-launch {-E|--startup}   [OPTIONS] [ACTID|DESKTOP|COMMAND]
 xdg-launch {-E|--session}   [OPTIONS] [ACTID|DESKTOP|COMMAND]
 xdg-launch {-h|--help} [OPTIONS] [APPSPEC [FILE|URL]...|COMMAND]
 xdg-launch {-V|--version}
 xdg-launch {-C|--copying}

💖 DESCRIPTION 💖

xdg-launch is a "C" language program (yes, an actual compiled icon 💅) that you can use to launch XDG desktop applications with startup notification. The way it does this: you can launch applications by application id, by mime type, by menu category, or by command line. And if you want, you can hand it a file or a URL too. Obsessed, honestly. 🦋

🌈 ARGUMENTS 🌈

The program accepts the following arguments (yes, all of them, I'm not skipping a single one):

⭐ APPSPEC = {ACTID|MIMETYPE|CATEGORY|DESKTOP}

Specifies the XDG desktop application to launch. The application specifier, APPSPEC, can be one of the following:

💫 ACTID = APPID[:ACTION]

Specifies the application identifier and optional action of an XDG desktop application to launch.

  • [{-a,--appid}] APPID Specifies the application identifier of an XDG desktop application to launch. The application identifier, APPID, can be one of the following:
    1. The name of a desktop entry file without the .desktop suffix (e.g. "gvim"); the name may contain a "/" if it is specified relative to a user or system application directory, in which case it must not start with a "/" or ".".
    2. The name of a desktop entry file with the .desktop suffix (e.g. "gvim.desktop"); the same restrictions as (1), above, apply; or,
    3. The full path (absolute or relative) and file name of a desktop entry file (e.g. /usr/share/applications/gvim.desktop); the full path must contain at least one "/" and start with either a "/" or a ".".

The application identifier, APPID, can alternately be specified as an option argument using the --appid option.

  • [{-A,--action}] ACTION Specifies the action of an XDG desktop application to launch. The action must appear in the Actions key in the desktop entry and have a corresponding [Desktop Action ACTION] group defining the action. Note that auto-start desktop entries do not have actions.

The action, ACTION, can alternately be specified as an option argument using the --action option.

💫 [--mimetype] MIMETYPE

A registered mime type of the form "type/subtype". This corresponds to the mime type of a file or scheme handler that will identify the application to launch.

The mime type, MIMETYPE, can alternatively be specified as an option argument using the --mimetype option. Where the mime type would conflict with an existing APPID, it must be specified with the --mimetype option.

💫 [--category] CATEGORY

An XDG menu specification category that identifies the application to launch.

The XDG menu specification category, CATEGORY, can alternatively be specified as an option argument using the --category option. Where the category would conflict with an existing APPID, it must be specified with the --category option.

💫 [--desktop] DESKTOP

The XDG menu specification desktop name that identifies the X session for which to launch. This APPSPEC is only applicable when --xsession, --startup or --session is specified.

The XDG menu specification desktop name, DESKTOP, can alternatively be specified as an option argument using the --desktop option. Where the desktop name would conflict with an existing APPID, it must be specified with the --desktop option.

Providing a non-option application specifier argument is mandatory unless the --exec, --appid, --mimetype or --category options are specified, in which case it should not be specified as a non-option argument. iykyk 🫶
  • [{-f,--file}] FILE ... Specifies the file name with which to launch the application. This is used in %f substitutions in the "Exec" field of the XDG desktop entry file or --exec command line. This may also be Specified with the --file option. The option or argument can be repeated to specify multiple files.
  • [{-u,--url}] URL ... Specifies the URL with which to launch the application. This is used in %u substitutions in the "Exec" field of the XDG desktop entry file or --exec command line. This may also be specified with the --url option. The option or argument can be repeated to specify multiple URLs.
Mixing FILE and URL arguments or options is not currently recommended. Like, don't do it, bestie. 🙈

👑 COMMAND = {{-x,--exec} "EXEC ARGUMENT..."|-e EXEC ARGUMENT...}

When specified with -e, this option must be the last option on the command line. Options processing stops abruptly at this option and remaining arguments are considered to be the command and the command arguments to execute. xdg-launch will execve(3) the arguments under startup notification control in a similar fashion to "sh -c". This may also be specified as a single string argument to "sh -c" using the --exec option.

💅 ARGUMENT OPTIONS 💅

Arguments can be optionally provided using the following options:

  • -a, --appid APPLICATION_ID — Override the application identifier. This overrides the name of the XDG application file. When unspecified, the default is to use the non-option APPID argument to determine the application identifier. This value, when available, is placed in the "APPLICATION_ID" key-value entry in the startup notification "new:" message.
  • -A, --action ACTION — Specifies a desktop action, ACTION, to perform instead of the default action. The default is to perform the default action in the desktop entry file. This value, when available, is placed in the "ACTION" key-value entry in the startup notification "new:" message.
  • --mimetype MIMETYPE — Specify a registered mime type, MIMETYPE, of the form "type/subtype". This corresponds to the mime type of a file or scheme handler that will identify the application to launch.
  • --category CATEGORY — Specify an XDG menu specification category, CATEGORY, that identifies the application to launch.
  • --desktop DESKTOP — Specify an XDG menu specification desktop environment name, DESKTOP, that identifies the X session for which to launch.
  • -f, --file FILE — Specifies a file name, FILE, to be substituted into the XDG desktop entry "Exec" command in accordance with XDG desktop entry specifications. The default is to use the non-option FILE argument, or no file name. When --url or URL is specified as a file:// URL, this option defaults to the URL with the file: portion removed.
  • -u, --url URL — Specifies a URL, URL, to be substituted into the XDG desktop entry "Exec" command in accordance with XDG desktop entry specifications. The default is to use the non-option URL argument, or no URL. When --file or FILE is specified, this option defaults to the FILE with a file:// portion prefixed.
  • -x, --exec COMMAND — Specifies the command to execute. This overrides the "Exec" field of the XDG desktop entry file. When unspecified, the default is the "Exec" field of the XDG desktop entry file.

🔥 OPTIONS 🔥

The options that are detailed below are recognized by xdg-launch. xdg-launch uses getopt_long_only(3), so unambiguous abbreviations of long options and long options with a single dash are also supported. (yes, single dash long options, she's flexible like that 💅)

🎀 COMMAND OPTIONS 🎀

The default is to launch the application specified by "APPSPEC". When any of the following options are specified, the command mode changes.

Only one of --autostart, --xsession, --startup or --session can be specified. Pick a lane, bestie. ✋
  • -U, --autostart — Interpret and search for the desktop entry file as an "AutoStart" desktop entry instead of an "Application" desktop entry. This is the default when invoked as xdg-autostart. The "LAUNCHER" will default to xdg-autostart instead of xdg-launch. Aside from these differences, the launcher operates in the same fashion. This option is intended for launching individual autostart entries.
  • -X, --xsession — Interpret and search for the desktop entry file as an "XSession" desktop entry instead of an "Application" desktop entry. This is the default when invoked as xdg-xsession. The "LAUNCHER" will default to xdg-session instead of xdg-launch. Aside from these differences, the launcher operates in the same fashion. This option is intended for launching window managers.
  • -E, --session — Interpret and search for the desktop entry file as an "XSession" desktop entry instead of an "Application" desktop entry. This is the default when invoked as xdg-session. The "LAUNCHER" will default to xdg-session instead of xdg-launch. This option, therefore, acts like the --xsession option, with the exception that the program also performs autostart for the window manager by executing the necessary autostart desktop entries according to the XDG autostart specification. This option is useful for launching a light-weight session for use with a light-weight window manager.
  • -B, --startup — Interpret and search for the desktop entry file, if specified, as an "XSession" desktop entry instead of an "Application" desktop entry. This is the default when invoked as xdg-startup. The "LAUNCHER" will default to xdg-startup instead of xdg-launch. This option, therefore, acts like the --session option, with the exception that the program only performs autostart by executing the necessary autostart desktop entries according to the XDG autostart specification, and does not launch a window manager. This option is useful for launching autostart entries after a light-weight window manager has already started.
  • -I, --info — When specified, instead of launching the application selected, print information about the final desktop file selected to launch the actions that would have been taken to launch the desktop entry if this option had not been specified. This is equivalent to a dry run. (screenshot the fit before you commit to the fit, basically 📸)
  • -c, --chain — tells xdg-launch that this launch is chained onto a launch that's already in progress 💫. It's the default whenever a DESKTOP_STARTUP_ID environment variable already exists when xdg-launch starts up. That said, you can still pass it explicitly to make sure no extra launch operation gets kicked off when xdg-launch is sitting in the Exec key of a desktop entry file. Heads up though: once you use it, none of the options that follow are significant — the only exceptions are "HISTORY OPTIONS" and "GENERAL OPTIONS". Peep "LAUNCH CHAINING" below for the whole story 🫶.
  • -h, --help — prints usage info to standard output and dips ✌️.
  • -V, --version — prints the detailed version info and bounces 👋.
  • -C, --copying — prints the detailed copying permissions and exits 🎀.

🌸 LAUNCH OPTIONS 🌸

okay so these next ones all shape the parameters of the startup notification "new" message that gets sent out for the launch 💌.

  • -L, --launcher LAUNCHER — sets the string used as the launcher when a startup notification identifier gets generated. Default? The name of this program, like "xdg-launch" ✨.
  • -l, --launchee LAUNCHEE — sets the string used as the launchee when generating that startup notification identifier. Default is the application identifier 🏷️.
  • -S, --sequence SEQUENCE — sets the sequence number used when generating the startup notification identifier. When you don't specify one, the default is zero (0) 🔢.
  • -n, --hostname HOSTNAME — sets the host name used when generating the startup notification identifier. Unspecified? It defaults to whatever hostname -f spits out 💻.
  • -m, --monitor MONITOR — picks the monitor, MONITOR, that the XDG application, APPID, launches on. If you leave it out, it uses the monitor the pointer is currently chilling on 🖱️. MONITOR has to be the numerical zero-based index of the monitor you want. This value goes into the "MONITOR" key-value entry of the startup notification "new" message. No value gets placed at all when Xinerama (or RANDR) isn't active for the display, or for single-screen Xinerama (or RANDR) setups — in that case "SCREEN" is used instead. See "Multiple Monitors" below 👀.
  • -s, --screen SCREEN — picks the screen, SCREEN, that the XDG application, APPID, launches on. Unspecified means the screen containing the pointer is used 🖰. For single-screen Xinerama (or RANDR) setups, the value of MONITOR is used for SCREEN. SCREEN must be the numerical zero-based index of the screen you want. This value lands in the "SCREEN" key-value entry of the startup notification "new" message. No value gets placed when there's only one screen and Xinerama (or RANDR) isn't active for the display. See "Multiple Screens" below 💅.
  • -w, --workspace DESKTOP — picks the desktop, DESKTOP, that the XDG application launches on. Unspecified? Default is the current desktop for the screen, SCREEN. This value goes into the "DESKTOP" key-value entry of the startup notification "new" message 🗂️.
  • -t, --timestamp TIMESTAMP — sets an X Server time stamp that corresponds to the X window event which caused the launch to happen ⏱️. This is literally only useful when you also specify an APPID argument. If you don't give a time stamp, xdg-launch uses the time of the last event (or it generates an event) for the time stamp. The resulting time stamp — whether you specified it or not — gets used in the "_TIME" portion of the startup notification identifier, and in the "TIMESTAMP" key-value entry of the startup notification "new" message 🔥.
  • -N, --name NAME — sets the name of the XDG application. This overrides the "Name" field from the XDG desktop entry file. When unspecified, the default is the "Name" field from the XDG desktop entry file. This value, when it's available, is placed in the "NAME" key-value entry of the startup notification "new" message 🌟.
  • -i, --icon ICON — sets the icon name of the XDG application, ICON. Overrides the "Icon" field from the XDG desktop entry file. When unspecified, default is the "Icon" field from the XDG desktop entry file. This value, when available, goes in the "ICON" key-value entry of the startup notification "new" message 🎨.
  • -b, --binary BIN — sets the name of the binary for the XDG application, BIN. This overrides the "TryExec" and "Exec" fields from the XDG desktop entry file. When unspecified, the default is the "TryExec" field, or the "argv[0]" option of the "Exec" field, from the XDG desktop entry file. This value, when available, is placed in the "BIN" key-value entry of the startup notification "new" message ⚙️.
  • -d, --description DESCRIPTION — sets the description of the XDG application, DESCRIPTION. Overrides the "Comment" field from the XDG desktop entry file. When unspecified, the default is to use the "Comment" field from the XDG desktop entry file, or a descriptive sequence such as "Staring Name". This value, when available, is placed in the "DESCRIPTION" key-value entry of the startup notification "new" message 📝.
  • -W, --wmclass WMCLASS — sets the window manager class of the top-level window that the XDG application is expected to map (this gets matched against the "res_name" or "res_class" of the "WM_CLASS" property on a window). Overrides the "StartupWMClass" field of the XDG desktop entry file. When unspecified, the default is the "StartupWMClass" field of the XDG desktop entry file. This value, when available, is placed in the "WMCLASS" key-value entry of the startup notification "new" message 🪟.
  • -q, --silent SILENT — sets a boolean value (0/1) deciding whether visual feedback should be provided for the launching XDG application, SILENT 🙈. Normally, when unspecified, visual feedback gets figured out from whether a "StartupNotify" or "StartupWMClass" field has a value in the XDG desktop entry file. The SILENT argument should be some boolean value like 0 or 1 or "yes" or "no" or "true" or "false". The default when unspecified is to determine the value from the other fields of the XDG desktop entry file. This value, when available, is placed in the "SILENT" key-value entry of the startup notification "new" message 🤐.

When unspecified, the "SILENT" argument to the startup notification message is set when the XDG desktop entry has neither a "StartupNotify" nor a "StartupWMClass" field, or it only has a "StartupNotify" field but that one is set to false 🫥.

  • -p, --pid PID — sets the process identifier for the launch sequence. Default is the process identifier of the xdg-launch program itself 🆔.
  • --ppid — sets the process identity of a sub-reaper process under which the launched application should be re-parented when its parent terminates 🧬. This option defaults to the environment variable ${XDG_SESSION_PID} and, if that doesn't exist, the process group leader of the process invoking xdg-launch. If you want to keep it from being set automatically, set it to zero. This is super useful for applications launched by a window manager — it makes sure that if the window manager crashes, it can be restarted by the session and the application's child processes get re-parented to the session 🛟.

🦋 CONTEXT OPTIONS 🦋

Context options are how you guide the appropriate selection of screen and monitor 👑. When the program runs from a key binding associated with a window manager, the most appropriate screen or monitor is the one containing the window that currently has the keyboard focus ⌨️. When the program launches from a pointer button press, the most appropriate screen or monitor is the one containing the pointer 🖱️.

  • -P, --pointer — when specified, xdg-launch determines the screen or monitor from where the pointer currently is. Use this when xdg-launch gets invoked from a menu or a mouse binding 🖲️. This option has no effect on the screen when the screen was specified using either the DISPLAY environment variable or the --screen option. And this option has no effect on the monitor when --monitor is also specified 🚫.

Only one of --pointer or --keyboard can be specified 👆.

  • -K, --keyboard — when specified, xdg-launch determines the screen or monitor from the location of the window with the current keyboard focus ⌨️✨. Use this when xdg-launch gets invoked from a command line or a keyboard binding. This option has no effect on the screen when the screen was specified using either the DISPLAY environment variable or the --screen option. And this option has no effect on the monitor when --monitor is also specified 🚫.

Only one of --pointer or --keyboard can be specified 👆.

💜 ASSIST OPTIONS 💜

xdg-launch can assist a window manager that isn't startup-notification aware with completing startup notification, and it can also establish the initial settings of some NetWM/EWMH properties on any application windows 🪄. These options control that behaviour.

  • --assist — normally xdg-launch figures out whether the window manager and application toolkit need help with startup notification. The default, when there's a window manager that supports startup notification, is to not provide any assistance. This option requests that xdg-launch provide startup notification assistance to any window manager 🤝.
  • --no-assist — normally xdg-launch figures out whether an existing window manager and application toolkit need help with startup notification. The default, when there's a window manager that doesn't support startup notification, is to provide assistance. This option requests that xdg-launch not provide startup notification assistance to any window manager 🙅‍♀️.

🎀 TOOL WAIT OPTIONS 🎀

The following tool wait options give you functionality equivalent to that of xtoolwait(1) 🧰.

  • -T, --toolwait — normally xdg-launch doesn't exit; it replaces the foreground process with the application using execve(3). When you specify this option, the behaviour changes: xdg-launch executes the application in a background process and exits once the application has started 🏃‍♀️. The criteria for when the application counts as started depends on the other "JOB CONTROL OPTIONS" 👀.
  • --timeout [SECONDS] — how long we're willing to sit around waiting for startup to finish before we just call it and say the app is launched. Leave the value off, or pass zero (0), and it waits indefinitely 💀 (yes, forever, no cap). Default is fifteen (15) seconds — same default as xtoolwait(1). Heads up: this timeout only applies to startup notification completion, nothing else.
  • --mappings NWINDOWS — okay so normally, when we're not expecting a startup notification completion message, xdg-launch(1) says "yep, launched" the moment it maps the first client window. With this option you tell it to hold on until NWINDOWS mappings have happened first. Unspecified default is one window 🎀
  • --withdrawn — xtoolwait(1) has to be told when an app is a Window Maker dockapp so it can detect windows mapped in the "WithdrawnState". xdg-launch picks up Window Maker dockapps automatically ✨, so you only need this when the automatic detection fails for some reason. It exists for compatibility with xtoolwait(1) and, lowkey, mostly doesn't change behaviour.
  • --pid — for compatibility with xtoolwait(1): asks xdg-launch to print the process id of the command to standard output. When you use this, xdg-launch redirects the application's standard output to standard error so things don't get messy. Only one of -pid or -wid can be specified.
🙈 note: this option conflicts with the usage of the --pid option, above — but this usage doesn't accept an argument, so like, that's the difference, bestie.
  • --wid — prints the id of the X window that caused startup completion to be signalled, to standard output, so you can feed it to tools like wmctrl(1) or xdotool(1). xdg-launch redirects the application's standard output to standard error when this option is specified. Only one of -pid or -wid can be specified. 💅
  • --noprop — when we're using a window being mapped to decide that startup notification is complete, this says: just use the creation of a top-level window as the criteria instead of expecting a "WM_STATE" property change.

🌸 SESSION OPTIONS 🌸

These ones are all about desktop session control 🫶 — they decide what conditions get awaited before your application or command actually launches. When you don't specify any session option, xdg-launch may figure out on its own which conditions need awaiting, depending on how --autowait and --no-autowait are set. Iconic behaviour tbh.

  • --autowait — normally, when xdg-launch is executing an autostart entry, it works out whether the app needs to wait for resources or a startup phase before launching. This option says: yes, do the wait when it's required. ⭐
  • --no-autowait — same situation (executing an autostart entry, normally works out whether the app needs to wait for resources or a startup phase), but this option says: don't wait for any resources or startup phase. periodt.
💖 real talk: some key fields in an app's .desktop file can specify the autostart phase (e.g. "AutostartPhase", "X-GNOME-Autostart-Phase"). When the --autostart option is specified, the setting of these key fields may affect the default settings of the session options above. In particular:
  • "Initialization" — when an autostart phase of "Initialization" is specified, xdg-launch will not wait for any desktop resource before running the application or command.
  • "WindowManager" — when an autostart phase of "WindowManager" is specified, or when --xsession is specified, xdg-launch will not wait for any desktop resource before running the application or command.
  • "Panel" — when an autostart phase of "Panel" is specified, xdg-launch will wait for a window manager (regardless of the --manager option) before continuing; however, it will not wait for a tray or pager. It'll only wait for a composite manager if --composite was specified.
  • "Desktop" — when an autostart phase of Desktop is specified, xdg-launch will wait for a window manager (regardless of the --manager option) before continuing. It will only await other resources if they've been explicitly specified with options.
  • "Applications" — when an autostart phase of Desktop is specified, or when no autostart phase is specified and --autostart is given, xdg-launch will wait for a window manager (regardless of the --manager option) before continuing; however, it will only await other resources if they've been explicitly specified with options. 💫

When "AutostartPhase" isn't specified, xdg-launch may use the category in the app's .desktop file to work out which autostart phase the application should be launched in, like this:

  • "DockApp" — apps in this category get launched in the "Applications" phase.
  • "TrayIcon" — apps in this category get launched in the "Applications" phase, and will wait for a system tray to appear before launching.
  • "Audio" — apps in this category will wait for an audio server to appear.
  • "SystemTray" — an application in this category will not wait for a system tray, because the application provides one.
  • "Pager" — an application in this category will not wait for a desktop pager, because the application provides one.
  • "Panel" — an application in this category will not wait for a system tray nor a desktop pager (as most panels provide these).

The options that follow are for specifying the conditions that must be awaited before xdg-launch will proceed to launch the application. None of these options has any effect when the --no-autowait option is specified 🚨

  • -M, --manager — awaits a window manager showing up before launching the application or command. Default behaviour is to not wait for any desktop resource before launching.
  • -Y, --tray — awaits a system tray showing up before launching the application or command. Default behaviour is to not wait for any desktop resource before launching.
  • -G, --pager — awaits a desktop pager (or desktop pager specification) showing up before launching the application or command. Default behaviour is to not wait for any desktop resource before launching.
  • -O, --composite — awaits a composite manager showing up before launching the application or command. Default behaviour is to not wait for any desktop resource before launching.
  • -R, --audio — awaits an audio server showing up before launching the application or command. Default behaviour is to not wait for any desktop resource before launching. 🎧
  • -g, --guard [SECONDS] — await resources for no longer than SECONDS seconds before continuing. No value, or a value of zero (0), means wait indefinitely for the resource. Default value is 2 seconds.
  • --delay SECONDS — delay for SECONDS seconds before launching an auto-start entry. Default value is zero (0) seconds. When it's non-zero, this option overrides the "X-GNOME-AUtostart-Delay" desktop entry field. ⏰

🦋 HISTORY OPTIONS 🦋

When simple applications are launched, files containing the history of recently launched applications get updated. These options control that whole vibe:

  • --history, --no-history — by default, when simple applications are launched, the files containing the history of recent applications and recently used files and URLs are updated. For other applications (auto-start, X session), histories aren't kept by default. These options specify whether histories are to be kept or not. 💾
  • -k, --keep NUMBER — sets the max number, NUMBER, of commands or application invocations kept in the recent history file. Minimum value is one, maximum value is 100, and the default when unspecified is 10. This option is ignored when history is not in effect.
  • -r, --recent FILENAME — sets the FILENAME of the recent history file. In exec mode, store the recent history of the executable in the file FILENAME; in exec mode the default is $XDG_CONFIG_HOME/xde/run-history. In application mode, store the recent history of the application in the file FILENAME; in application mode the default is $XDG_CONFIG_HOME/xde/recent-applications. This option is ignored when history is not in effect. 🗂️

🍓 CONTENT OPTIONS 🍓

These affect the current or future selection of an application by mime type or XDG category:

  • --set-default — when used with an APPID argument, says the selected application id is to be made the default for its mime-types and categories when successfully launched. The default is to not make the launched application the default for mime-type nor category.

It's the simple way of making an app the default for its mime-types and categories. For example:

$> xdg-launch --set-default chromium

will make chromium the default web browser. Either of the following command lines will then result in launching chromium:

$> xdg-launch text/html
$> xdg-launch WebBrowser

If the application id was already on the default list, it gets moved to the beginning of the list; otherwise it gets inserted at the beginning of the list. 👑

  • --set-preferred — when used with an APPSPEC argument, says the selected application id is to be added to the recommended list for its mime-types and categories when successfully launched. If the application id was already on the recommended list, it gets moved to the beginning of the list; otherwise it gets inserted at the beginning of the list. 💅
  • --default, --no-default — when used with a MIMETYPE or CATEGORY argument, specifies whether xdg-launch should consider the default application defined for the mime-type or category. (The default application setting is defined by the XDG mime-type specifications and is the familiar default used by most desktop file managers.) The default is to consider the default application. ✨
  • --recommend, --no-recommend — when you use this with a MIMETYPE or CATEGORY argument, it says whether xdg-launch should even look at the recommended applications defined for that mime-type or category. (The recommended applications setting is defined by the XDG mime-type specifications, and it's literally the familiar recommended list that most desktop file managers use, iykyk.) Default is: yes, it considers the recommended applications 💖
  • --fallback, --no-fallback — same situation, but for the fallback applications defined for the mime-type or category. (The fallback applications setting is defined by the XDG mime-type specifications, and again it's the familiar recommended list used by most desktop file managers.) Default is: yes, it considers the fallback applications too ✨

🌸 GENERAL OPTIONS 🌸

These are the general ones, bestie:

  • -v, --verbose [LEVEL] — prints diagnostic info to standard error while it's doing its thing. Repeat it to crank the verbosity up even higher. Default level? 1. 🎚️
  • -D, --debug [LEVEL] — prints debugging info to standard error during operation. Repeat it to push the debugging level up. Default level is 0. 🐛

💅 BEHAVIOUR 💅

okay so here's how xdg-launch actually behaves, character by character:

⏰ TIME STAMPS ⏰

xdg-launch is intended on being invoked directly from a user interface — think the root menu of a light-weight window manager, or an X windows application like a system tray menu. And to perform proper startup notification, it figures out the X server time stamp of the invocation like this:

  1. When xdg-launch is invoked directly (executed) from an application that has access to the X server event that invoked the launch, that app can hand the X server time stamp straight to xdg-launch with the --timestamp option (see "OPTIONS"). xdg-launch will use this time stamp when it generates the DESKTOP_STARTUP_ID and for the "TIMESTAMP" key-value pair in the startup notification "new" message. 🫶
  2. When xdg-launch is invoked by an application that doesn't have access to the X event that invoked the launch, xdg-launch will change the _TIMESTAMP_PROP property on the root window to obtain a time stamp. That's the whole trick — it means xdg-launch can just be executed using the execute mechanism of a light-weight window manager root menu or key binding. iconic. 👑
  3. When xdg-launch is invoked by another startup notification launcher, it grabs the time stamp (and other info) from the DESKTOP_STARTUP_ID environment variable. 🎀

🖥️ MULTIPLE HEADS 🖥️

xdg-launch fully supports multiple heads (screens) and Xinerama (or RANDR) multiple physical monitors per screen. no cap.

Multiple Screens

When there are multiple screens, some window managers will adjust the DISPLAY environment variable to include the screen number for launched applications. Example time: if the window manager DISPLAY environment variable is :7 and a program is launched on screen 1, that program gets launched with a DISPLAY environment variable of :7.1. So when xdg-launch detects a screen number in its DISPLAY environment variable, the screen it uses will be the one specified in the environment variable — unless the --keyboard, --pointer or --screen options are specified. And when xdg-launch launches the ultimate desktop application, it adjusts the DISPLAY environment variable to include the screen, because most applications launch on the default screen, and this manages to get the desktop application launching on the correct screen. ✨

Multiple Monitors

xdg-launch detects Xinerama and RANDR multiple monitor setups. When the --keyboard or --pointer options are specified, xdg-launch determines the monitor number from the keyboard focus window or pointer location, and that monitor number gets placed in the "MONITOR=" field of the startup notification "new" message. 💫

But here's the catch — launched desktop applications have no way of determining information outside of the DESKTOP_STARTUP_ID with which they were launched (the screen number can be obtained from the DISPLAY environment variable, that part's fine). The DESKTOP_STARTUP_ID is formatted (ala libstartup-notification) like this:

%s/%s/%d-%d-%s_TIME%lu

Where the fields are the launcher, launchee, pid, sequence, host and timestamp. The sequence number is of no use to the application, and it's also of no use to xdg-launch because the PID changes with each invocation. Therefore, when the launcher is xdg-launch, the application (or window manager) can use the sequence field as the monitor index. big brain energy fr fr 🧠

🐚 TERMINAL PROGRAMS 🐚

For desktop entries that set "Terminal=true", they may also set "StartupWMClass" to a class name specific to the program being executed. Most terminal programs (and xterm(1) specifically) can set the "WMCLASS" name and class to something other than that of the terminal program (i.e. instead of "xterm.XTerm"). When the desktop entries do so, xdg-launch will set the name attribute on the terminal to the name specified when the terminal is launched, if possible. This also permits, for terminal emulation programs such as xterm(1), the ability to set special terminal resources by application. Because not many desktop entry files do this, when no "StartupWMClass" is specified, the "APPID" or "BINARY" will be used instead and "StartupWMClass" will be automatically populated. 💅

This procedure provides additional assistance to window managers when terminal emulation programs do not properly observe startup notification. (For example, xterm(1) does not properly observe startup notification, even though it properly observes X11 Session Management, whereas many other terminal emulators support both.) 😭

You can change the default terminal emulation program used when these applications are launched by using environment variables (see "ENVIRONMENT") or X resources (see "X RESOURCES"). 🎀

Terminal programs that are known to xdg-launch are:

When the TERMINAL environment variable is set to one of these terminals (a terminal known to xdg-launch), it will automatically determine the corresponding XDG_TERMINAL and XDG_TERMRESN commands when they are not specified. See "ENVIRONMENT" below. When no terminal environment variables are specified, terminal programs will be detected in the user's PATH in the order specified above. Note that terminix(1) and hyper(1) are currently unknown. XDG_TERMINAL and XDG_TERMRESN must currently be specified to use those or other unknown terminals. 🙈

See "ENVIRONMENT" below for more information on selecting the terminal to use for launching applications that need one. 🐚

🚀 AUTO START SESSION 🚀

When --session is specified, the program starts the XDG auto start procedure before launching the window manager specified by the APPID or --exec command. xdg-launch creates a session by launching autostart desktop entries in child processes, and then executes the APPID or --exec command for the window manager in the parent process. It attempts to become a process group leader before launching children. This should ultimately leave any child processes as children of the window manager. The window manager is executed in the parent process and, therefore, the parent process will not exit until the window manager exits. 👑

When --startup is specified, or no APPID or --exec command is specified, instead of starting a window manager, it establishes children so that they will be re-parented to the process group leader when the parent process exits. 🦋

🧰 TOOL WAIT 🧰

xdg-launch can also be used to replace xtoolwait(1) for XDG applications when invoked with the appropriate options. A convenience script, xdg-toolwait(1), is provided that mimics the options of xtoolwait(1). See xdg-toolwait(1) for more information. 🎀

🪟 WINDOW MANAGERS 🪟

xdg-launch interacts with window managers in the following ways:

  1. xdg-launch creates startup notification identifiers using the technique from the libstartup-notification library. This consists of the following:
while((p = strchr(launcher, '/'))) *p = '|';
while((p = strchr(launchee, '/'))) *p = '|';
sprintf(id, "%s/%s/%d-%d-%s_TIME%lu",
    launcher, launchee, getpid(), monitor,
    hostname, timestamp);

Compliant applications will place the startup notification identifier from the DESKTOP_STARTUP_ID environment variable in the _NET_STARTUP_ID property on its group leader top-level window before it is mapped. The window manager can use the "_TIME%lu" portion of the startup identifier to determine the X server time stamp for the event that launched the application. When the client does not set an initial _NET_WM_USER_TIME, this time stamp can be used in its stead. It can also use the "/%d-" portion of the startup identifier to determine the process identifier, the "-%d-" portion to determine the monitor on which to start the application, and the "-%s_TIME" portion of the identifier to determine the host name of the launching machine. 🌈

  1. Window managers that monitor startup notification messages may also use the "TIMESTAMP=" key-field entry in the "new:" message for this purpose, particularly when the "WMCLASS=" field matches the resource name or class of a newly mapped top-level window. ✨
  2. xdg-launch neither changes nor removes the startup notification sequence and is only responsible for issuing in the "new:" or "change:" message. The window manager or desktop environment should issue a "remove:" message when it first manages a top-level window with a resource name or class than matches the "WMCLASS=" field of an outstanding "new:" message. 💅
  3. Window managers that monitor startup notification messages and associate them with managed top-level windows may use the following fields to populate missing properties on those windows — yes bestie, your WM can literally fill in the blanks 💅:
    • "ID=" — the window manager may use this field to populate the _NET_STARTUP_ID property on the window (group) when it's missing.
    • "HOSTNAME=" — the window manager may use this field to populate the WM_CLIENT_MACHINE property when it's missing or isn't a fully qualified domain name. This field can also be derived from the "ID=" field.
    • "PID=" — the window manager may use this field to populate the _NET_WM_PID property when it's missing. This field can also be derived from the "ID=" field.
    • "MONITOR=" — the window manager may use this field to choose the Xinerama (or RANDR) screen on which the top-level window (group) will be mapped. It may also be used to populate the _NET_WM_FULLSCREEN_MONITORS property when it's missing.
    • "SCREEN=" — the window manager may use this field to choose the Xinerama (or RANDR) or multi-head screen on which the top-level window (group) will be mapped. When it specifies a Xinerama (or RANDR) screen, it may also be used to populate the _NET_WM_FULLSCREEN_MONITORS property when it's missing.
    • "DESKTOP=" — the window manager may use this field to populate the _NET_WM_DESKTOP, _WIN_WORKSPACE, or _DT_WORKSPACE_PRESENCE property when missing or otherwise unspecified.
    • "TIMESTAMP=" — the window manager may use this field to populate the _NET_WM_USER_TIME property when it's missing. This field can also be derived from the "ID=" field.
    • "NAME=" — the window manager may use this field to populate the WM_NAME, _NET_WM_NAME, or _NET_WM_VISIBLE_NAME properties when they're missing or empty.
    • "ICON=" — the window manager may use this field to establish an icon for the window when the WM_ICON, _NET_WM_ICON or _KDE_NET_WM_ICON properties are missing or otherwise unusable.
    • "WMCLASS=" — the window manager may use this field to associate a startup notification sequence with a newly mapped top-level window.
    • "COMMAND=" — the window manager may use this field when the WM_COMMAND field is missing (and for the same purposes). Because rather complicated shell expansion would be required to expand the command, it cannot be used to populate the WM_COMMAND property; however, it may be executed by passing it literally as a shell command. I suppose one could populate WM_COMMAND with "sh", "COMMAND" if necessary.

🔗 LAUNCH CHAINING 🔗

So the whole point here: xdg-launch can be used inside a desktop entry file, and for that it supports launch chaining. Iconic. ✨ When a DESKTOP_STARTUP_ID environment variable is set before the program is executed, xdg-launch assumes it's been executed from within a desktop entry file. The normal behaviour in this case is to act as normal — except that a "change:" message is sent where a "new:" message would be sent.

Now, because this may be confusing to some desktops or launch monitors, and may confuse a window manager that supports desktop startup notification completion, xdg-launch attempts to detect the situation where it's used to launch a desktop entry that uses xdg-launch (or one of its derivatives) in the Exec line. In the case that it detects a chained invocation, it simply executes the command without setting the DESKTOP_STARTUP_ID and without sending a "new:" message. Then the chained invocation performs startup notification as though it was invoked by itself. Recursive slay, honestly 💅.

To handle the case where a different launch is used to launch a desktop entry that contains an xdg-launch command, xdg-launch also supports the --chain option. When the --chain option is specified, the launch chaining behaviour is invoked. The differences are as follows:

  1. When the xdg-launch program starts, and there's no DESKTOP_STARTUP_ID environment variable set, it behaves normally; when it is set, the chaining behaviour is invoked, and the following differences apply:
  2. When launching the chained application, no "new:" or "change:" message will be sent and the DESKTOP_STARTUP_ID environment variable will be passed to the chained application unchanged. The options described under "LAUNCH OPTIONS" and "CONTEXT OPTIONS" are ignored.
  3. No tool wait, assistance, wait for resources, nor content setting procedures will be invoked. The options described under "ASSIST OPTIONS", "TOOL WAIT OPTIONS", "SESSION OPTIONS" and the set operations of "CONTENT OPTIONS" are ignored.
  4. The chained application will be executed in replacement for the xdg-launch program and no children will be spawned.

Chaining launches in this fashion is intended to be used to allow an xdg-launch command in a desktop entry file. Intended uses are with the --mimetype and --category methods of specifying an application to launch. A set of "preferred" application desktop entries are included in the distribution of xdg-launch. See the following desktop entry files installed in the /usr/share/applications directory 🫶:

  • preffered-execute.desktop — launches the user's preferred run dialog with the Exec key: "xdg-launch --chain RunCommand".
  • preffered-file-manager.desktop — launches the user's preferred file manager with the Exec key: "xdg-launch --chain FileManager".
  • preffered-mail-reader.desktop — launches the user's preferred mail reader with the Exec key: "xdg-launch --chain MailReader".
  • preffered-terminal.desktop — launches the user's preferred terminal with the Exec key: "xdg-launch --chain TerminalEmulator".
  • preffered-text-editor.desktop — launches the user's preferred text editor with the Exec key: "xdg-launch --chain TextEditor".
  • preffered-web-browser.desktop — launches the user's preferred web browser with the Exec key: "xdg-launch --chain text/html".
  • preffered-calculator.desktop — launches the user's preferred calculator with the Exec key: "xdg-launch --chain Calculator".

The xdg-launch package installs a reasonable distribution-provided prefapps.list file alongside the mimeapps.list file of the XDG "Association between MIME types and applications" specification. Bestie the packaging is so tidy 💖.

🕰️ RECENTLY USED FILES, URLS, APPLICATIONS 🕰️

By default, when simple applications are launched by xdg-launch, files that retain the history of recently used files, URLs and applications are automatically updated. When other applications (auto-start, X session) are launched, histories are not kept by default. Although the use of the --history and --no-history options overrides the default behaviour, the default is sufficient for the purpose of properly updating recent use files. Lowkey well-designed ngl 🌸.

Histories are written to three pairs of files (see "FILES"). The first pair keeps recently executed commands and recently launched applications in a simple text format, one per line, with the most recent at the top. These two files were historically used by xde-run(1) and xde-app(1). The default files are $XDG_CONFIG_HOME/xde/run-history and $XDG_CONFIG_HOME/xde/recent-applications.

The second pair keeps recently used files and URLs in a non-XBEL, XML file format used historically by GNOME. Applications are recorded in each as a reference to the desktop entry, .desktop file of the application. The second in the pair only contains the .desktop entries, while the first contains all file and URL references. Some older GTK application file selection dialogues use these files. The default files are $HOME/.recently-used and $HOME/.recent-applications.

The last pair keeps recently used files and URLs in an XBEL, XML file format that is currently part of the XDG specifications. Files and URLs are contained in the first of the pair, and application .desktop entries are only contained in the second. The default files are $XDG_DATA_HOME/recently-used.xbel and $XDG_DATA_HOME/recent-applications.xbel.

Current file dialogues and applications use only the last pair of XBEL-formatted files. Applications that provide menu and dialogue access to both lists are xde-run(1), xde-app(1) and xde-recent(1). Iconic trio, honestly 👑.

🌱 ENVIRONMENT 🌱

okay bestie, these are the env vars xdg-launch peeks at 👀 — every single one, no skipping:

  • DISPLAY — used by xdg-launch to figure out the X display and default screen it was invoked on. your whole vibe check for "where am i" ✨
  • DESKTOP_STARTUP_ID — used by xdg-launch at program startup to figure out whether it itself got launched with startup notification. if so, the DESKTOP_STARTUP_ID gets reused. this env var is set to the startup notification identifier right before executing the launched program. see "LAUNCH CHAINING" for the deets 🫶
  • LANG — used by xdg-launch at program startup to decide which language to pick for the "Name=" and "Comment=" fields in the desktop entry file 🌸
  • HOME — used by xdg-launch to find the user's home directory 🏠
  • XDG_DATA_HOME — used by xdg-launch to find the user's XDG data directory. defaults to $HOME/.local/share. the applications (or xsessions) subdirectory under this directory is the first one searched to locate desktop entry files. see the XDG Desktop Entry file specification for more 💖
  • XDG_DATA_DIRS — used by xdg-launch to find the system XDG data directories. defaults to /usr/local/share:/usr/share. the applications (or xsessions) subdirectory under these directories gets searched in order to locate desktop entry files. again, XDG Desktop Entry file spec if you want the lore ✨
  • XDG_CONFIG_HOME — used by xdg-launch to determine the user's XDG configuration directory. defaults to $HOME/.config. the autostart subdirectory under this directory is the first one searched to locate desktop entry files. XDG Desktop Entry file spec, you already know 🌈
  • XDG_CONFIG_DIRS — used by xdg-launch to find the system XDG configuration directories. defaults to /etc/xdg. the autostart subdirectory under these directories gets searched in order to locate desktop entry files. XDG Desktop Entry file spec says hi 🎀
  • XDG_SESSION_PID — used by xdg-launch to set the sub-reaper process of launched applications. heads up: when doing autostart, xdg-launch will set this env var to its own PID when the variable isn't already set 💅
  • XDG_TERMINAL — used by xdg-launch as the command to prefix to the exec line of terminal applications, so it can launch applications inside a terminal 🖥️
  • XDG_TERMRESN — used by xdg-launch as the command to prefix to the exec line of terminal applications so it can launch applications inside a terminal when a resource name is available to be set on the terminal. (not necessarily defined for all terminal types — so don't come for her if it's missing 🙈)
  • TERMINAL — used by xdg-launch as the name of the preferred terminal program to run. if this terminal is known to xdg-launch, it'll automatically figure out the matching XDG_TERMINAL and XDG_TERMRESN commands when they aren't specified. see "TERMINAL PROGRAMS", above, for the list of known terminal emulation programs 👑

📁 FILES 📁

xdg-launch is obsessed with these files, fr fr:

  • $XDG_CONFIG_HOME/xde/run-history — the default location of the run-history file. it's a simple text file holding the commands that were last run with the xde-run(1) dialog, one per line, with the oldest entries lower in the file. for later use by xde-run(1), xdg-launch adds an entry to this file containing the command line that was executed 📝
  • $XDG_CONFIG_HOME/xde/recent-applications — the default location of the recent-applications file. simple text file, application ids that were last run with the xde-app(1) dialog, one per line, oldest entries lower in the file. for later use by xde-app(1), xdg-launch adds an entry containing the application id that was launched 🍓
  • $XDG_DATA_HOME/recently-used, $HOME/.recently-used — the default locations of the non-XBEL-formatted, co-mingled, recently used files and URLs. when the first location isn't present, the second is used. this co-mingled file predates the separated $HOME/.recent-applications file and records recent applications by listing the .desktop file as a recently used file 🌀
  • $HOME/.recent-applications — the default location of the non-XBEL-formatted, separate, recent applications file. it records recent applications by listing the .desktop file as a recently used file. the difference between this file and the $HOME/.recently-used file? this one only records recently used .desktop files 💫
  • $XDG_DATA_HOME/recently-used.xbel — the default location of the XBEL-formatted recently used files and URLs file. it only records files and URLs used by launched applications. .desktop files are not recorded here 🚫
  • $XDG_DATA_HOME/recent-applications.xbel — the default location of the XBEL-formatted rececent applications file. it only records launched applications (by .desktop file) 🎀
  • $HOME/.gtkrc-2.0.xde — the location of the XDE theme file that'll be used for the GTK theme when it exists. the program will also respect the "_XDE_THEME_NAME" property on the root window of the screen the program was launched for 🌸
  • $desktop-mimeapps.list, mimeapps.list — these files get searched in $XDG_CONFIG_HOME, $XDG_CONFIG_DIRS, $XDG_DATA_HOME/applications, $XDG_DATA_DIRS/applications to determine associations between MIMETYPE and APPLICATION_ID. the user's $XDG_CONFIG_HOME/$desktop-mimeapps.list file is altered when --set-default or --set-preffered are specified 🔥
  • $desktop-prefapps.list, prefapps.list — these files get searched in $XDG_CONFIG_HOME, $XDG_CONFIG_DIRS, $XDG_DATA_HOME/applications, $XDG_DATA_DIRS/applications to determine associations between CATEGORY and APPLICATION_ID. the user's $XDG_CONFIG_HOME/$desktop-prefapps.list file is altered when --set-default or --set-preffered are specified 💅

💀 BUGS 💀

xdg-launch has way too many options. like, iconic levels of too many. that's the bug. it's giving "she has a lot of flags and she's not sorry" 😭

please report other bugs to the source code repository at <https://github.com/bbidulock/xdg-launch/issues> 🫶

👀 SEE ALSO 👀

go read these bestie, they're all in the group chat:

xdg-show(1), xdg-assist(1), xdg-monitor(1), xdg-toolwait(1), xdg-autostart(1), xdg-xsession(1), xdg-session(1), xde-run(1), xde-app(1), xde-recent(1), execve(3), getopt_long_only(3), xtoolwait(1), wmctrl(1), xdotool(1), xterm(1), Startup Notification <http://standards.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt> 🌈

🫶 AUTHOR 🫶

Brian Bidulock <mailto:bidulock@openss7.org> — the main character who wrote all this 💜

and that's the whole page bestie!! this gorgeousness is xdg-launch 1.12, dated 2022-01-28 — screenshot it, cite it, put it on your fridge, periodt 💖✨🎀

📦 where this page comes from