NAME

       xdg-terminal-exec - Default Terminal Execution Utility

SYNOPSIS

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

DESCRIPTION

       Shell-based  implementation  of the proposed Default Terminal Execution Specification. Launches preferred
       terminal emulator, with or without optionally supplied command.

       Terminal emulators are selected among Desktop Entries that are installed on the system, or added by  user
       according  to  XDG  Desktop  Entry  Spec.  Only  valid  Entries  with  TerminalEmulator  category  and X-
       TerminalArgExec= key set are considered (X-TerminalArgExec= key is not required in compat mode).

       Command execution argument is determined by Entry's X-TerminalArgExec= key, (assumed to be -e by  default
       in  compat mode). If an actual -e or matching execution argument is given on the command line, it will be
       silently discarded along with any unsupported dashed option given before unambiguous command.

       It is assumed that the emulator handles command line  after  the  execution  argument  as  is  (preserved
       separate arguments).

OPTIONS

       Monolithic  options  starting with "--" are used to modify behavior of terminal (if supported by terminal
       and its entry):

       •   --app-id=app_id: set app-id (Wayland) or class (X11).
       •   --title=title: set tile of terminal.
       •   --dir=workdir: set workdir of terminal.
       •   --hold: instruct terminal to hold after command ends.

       Options for printing data instead of executing terminal:

       •   --print-id: print selected Desktop Entry ID. Action is appended delimited by ":".
       •   --print-path: print path to selected Desktop Entry. Action is appended delimited by ":".
       •   --print-content: print content of selected Desktop Entry. Conflicts with --print-cmd.
       •   --print-cmd[=printf_sequence]: print resulting command line, delimited by given printf sequence, "\n"
           by default. If sequence is "\n", output is also terminated with a newline.
       •   --print-delimiter=printf_sequence: printf sequenc to be used as the delimiterprint  between  multiple
           requested  statements, "\n" by default. If sequence is "\n", overall output is also terminated with a
           newline (without duplication in case command output already terminated on a newline).

       Selected data is printed in order:

       •   id
       •   path
       •   content
       •   cmd

CONFIGURATION

       Preferred terminals are configured by listing them in config files named ${desktop}-xdg-terminals.list or
       xdg-terminals.list placed in XDG Config hierarchy.

       ${desktop}  here  is  a  lowercased  string  that  is  matched  (case-insensitively)  against  items   of
       ${XDG_CURRENT_DESKTOP}  (a  colon-separated  list  of  names  for  the current DE) in order of decreasing
       priority.

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

       Terminals are listed by their Desktop Entry ID:

           terminal.desktop

       Optionally with Action ID suffixed via ":":

           terminal.desktop:action

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

       The first listed, found, and valid Desktop Entry is used.

       Otherwise fallback to the first found and valid Desktop Entry is performed.

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

           -terminal.desktop

       Prefixing entry with "+" will prevent it from later exclusion (first encountered directive wins):

           +terminal.desktop

       Special directives understood by this implementation (the first encountered directive is used):

           /enable_cache, /disable_cache

       The  cache  feature  allows storing selected terminal command line in ${XDG_CACHE_HOME} to bypass reading
       and parsing of configuration and Desktop Entries until changes are detected in  the  listing  of  Desktop
       Entry files or config files (enabled by default).

           /execarg_compat, /execarg_strict

       Compat  mode  (currently enabled by default) allows support for legacy [X-]ExecArg key and allows entries
       without execution argument, providing -e 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)
           Enable or disable cache feature.

       DEBUG (truthy or falsy value)
           Print debug info to stderr.

EXTERNAL LINKS

       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)

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

                                                   2025-09-08                               XDG-TERMINAL-EXEC(1)