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).

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-04-26                               XDG-TERMINAL-EXEC(1)