XDG-TERMINAL-EXEC(1)

📦
version 0.14.4 · 12 versions
, in arch rolling

💅 xdg-terminal-exec — the "which terminal do I open" queen 👑

so this is a page from the General Commands Manual bestie, and it's all about xdg-terminal-exec, the Default Terminal Execution Utility. yes she's shell-based, yes she's iconic ✨

🌸 NAME 🌸

xdg-terminal-exec — Default Terminal Execution Utility 🫶

🎀 SYNOPSIS 🎀

xdg-terminal-exec [options] [--] [command [arguments ...]]

🦋 DESCRIPTION 🦋

okay so first thing: this is a shell-based implementation of the proposed Default Terminal Execution Specification (say that five times fast 😭). what it actually does is launch your preferred terminal emulator, with or without a command if you felt like handing it one.

Terminal emulators get picked from Desktop Entries that are installed on the system, or ones you added yourself the way the XDG Desktop Entry Spec says to. no random entries though — only valid Entries that have the TerminalEmulator category and the X-TerminalArgExec= key set get considered. (tiny footnote: the X-TerminalArgExec= key is not required in compat mode, we'll get to that 💖)

The command execution argument comes from the Entry's X-TerminalArgExec= key — and in compat mode it's assumed to be -e by default. if an actual -e or a matching execution argument shows up on the command line, it gets silently discarded, along with any unsupported dashed option given before the unambiguous command. she said "not needed, bye" 💅

It's assumed the emulator handles the command line after the execution argument as-is (preserved separate arguments, no funny business).

✨ OPTIONS ✨

🎀 the monolithic -- options (terminal behaviour modifiers)

these modify the behavior of the terminal — if the terminal and its entry support it, no cap:

  • --app-id=app_id — sets app-id (Wayland) or class (X11) 🪟
  • --title=title — sets the tile of terminal (yes that's how the manpage says it, we keep it exactly like that 💀)
  • --dir=workdir — sets workdir of terminal 📁
  • --hold — instructs terminal to hold after the command ends, like a little pause for drama 🫶

🌈 the "just print it, don't run it" options

  • --print-id — print the selected Desktop Entry ID. Action gets appended delimited by ":".
  • --print-path — print the path to the selected Desktop Entry. Action gets appended delimited by ":".
  • --print-content — print the content of the selected Desktop Entry. Conflicts with --print-cmd ⚠️ (pick a lane bestie)
  • --print-cmd[=printf_sequence] — print the resulting command line, delimited by the given printf sequence, "\n" by default. if the sequence is "\n", output is also terminated with a newline.
  • --print-delimiter=printf_sequence — the printf sequence used as the delimiter between multiple requested statements, "\n" by default. if the sequence is "\n", the overall output is also terminated with a newline (and there's no duplication in case the command output already ended on a newline 💅).

👑 and the printing order — she has a sequence

Selected data is printed in this exact order, periodt:

  • id
  • path
  • content
  • cmd

💜 CONFIGURATION 💜

so how do you tell her which terminals you like? you list them in config files named ${desktop}-xdg-terminals.list or xdg-terminals.list, placed in the XDG Config hierarchy 🗂️

what's ${desktop}? it's a lowercased string that gets matched (case-insensitively) against the items of ${XDG_CURRENT_DESKTOP} — which is a colon-separated list of names for the current DE — in order of decreasing priority. iykyk.

The file is a simple newline-separated list. Empty lines and lines starting with # are ignored, and dangling whitespaces get trimmed ✂️

Terminals are listed by their Desktop Entry ID:

terminal.desktop

and optionally with an Action ID suffixed via ":":

terminal.desktop:action

Files get searched in XDG Config directories in order of decreasing priority. inside each directory, the prefixed files are parsed first, in the order listed in ${XDG_CURRENT_DESKTOP}. the unprefixed files are parsed last in each dir.

The first listed, found, and valid Desktop Entry is the one she uses. 💖

Otherwise? she falls back to the first found and valid Desktop Entry. no stress, she's got you.

🙈 excluding things from the fallback

Entries can be excluded from fallback by listing their ID prefixed with -:

-terminal.desktop

and prefixing an entry with + prevents it from later exclusion — first encountered directive wins:

+terminal.desktop

🧚 special directives

these are the special directives this implementation understands, and again the first encountered directive is used:

  • /enable_cache, /disable_cache — the cache feature lets her store the selected terminal command line in ${XDG_CACHE_HOME} so she can bypass reading and parsing of configuration and Desktop Entries until changes are detected in the listing of Desktop Entry files or config files. it's enabled by default ⚡
  • /execarg_compat, /execarg_strict — compat mode (currently enabled by default) allows support for the legacy [X-]ExecArg key and allows entries without an execution argument, providing -e as the default 🎀
  • /execarg_default:entry.desktop:arg — customize defaults for execution arguments of specific terminal entries (only in compat mode).

🍓 FILES 🍓

default paths for configuration files (in order of decreasing priority)

In ${XDG_CONFIG_HOME}:

  • ${HOME}/.config/${desktop}-xdg-terminals.list
  • ${HOME}/.config/xdg-terminals.list

In ${XDG_CONFIG_DIRS}:

  • /etc/xdg/${desktop}-xdg-terminals.list
  • /etc/xdg/xdg-terminals.list

In ${XDG_DATA_DIRS}:

  • /usr/share/xdg-terminal-exec/${desktop}-xdg-terminals.list
  • /usr/share/xdg-terminal-exec/xdg-terminals.list

default directories for Desktop Entries (in order of decreasing priority)

in ${XDG_DATA_HOME}:

  • ${HOME}/.local/share/applications/

in ${XDG_DATA_DIRS}:

  • /usr/local/share/applications/
  • /usr/share/applications/

cache file

  • ${XDG_CACHE_HOME}/xdg-terminal-exec

🌈 ENVIRONMENT 🌈

  • XTE_CACHE_ENABLED (truthy or falsy value) — enables or disables the cache feature.
  • XTE_DEBUG, DEBUG (truthy or falsy value) — prints debug info to stderr. perfect for when you're like "girl why did you pick that terminal" 😭

Proposal PR:

https://gitlab.freedesktop.org/terminal-wg/specifications/-/merge_requests/3/diffs

XDG Base Directory Spec:

https://specifications.freedesktop.org/basedir-spec/latest/

XDG Desktop Entry Spec:

https://specifications.freedesktop.org/desktop-entry-spec/latest/

Desktop Entry ID:

https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s02.html#desktop-file-id

Desktop Entry Action ID:

https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html

👑 AUTHORS 👑

Vladimir-csp (https://github.com/Vladimir-csp, https://gitlab.freedesktop.org/Vladimir-csp) — absolute main character energy, we stan 🫶

Thanks to Nathan Teodosio (https://github.com/nteodosio) for jump-starting the creation of this manpage. real one fr fr 💖

okay that's the whole page bestie, every flag, every path, every directive, nothing skipped, no cap 💅

and a cute little sign-off: this icon was dated 2026-10-28 and belongs to XDG-TERMINAL-EXEC(1) — go forth and open terminals, you're gonna slay 🦋🎀✨

📦 where this page comes from