.\" Generated by scdoc 1.11.3
.\" 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 "XDG-TERMINAL-EXEC" "1" "2026-01-17"
.PP
.SH NAME
.PP
\fBxdg-terminal-exec\fR - Default Terminal Execution Utility
.PP
.SH SYNOPSIS
.PP
\fBxdg-terminal-exec\fR [\fIoptions\fR] [--] [\fIcommand\fR [\fIarguments .\&.\&.\&\fR]]
.PP
.SH DESCRIPTION
.PP
Shell-based implementation of the proposed Default Terminal Execution
Specification.\& Launches preferred terminal emulator, with or without optionally
supplied command.\&
.PP
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 \fBTerminalEmulator\fR category and \fBX-TerminalArgExec=\fR key set are
considered (\fBX-TerminalArgExec=\fR key is not required in compat mode).\&
.PP
Command execution argument is determined by Entry'\&s \fBX-TerminalArgExec=\fR key,
(assumed to be \fB-e\fR by default in compat mode).\& If an actual \fB-e\fR 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.\&
.PP
It is assumed that the emulator handles command line after the execution
argument \fBas is\fR (preserved separate arguments).\&
.PP
.SH OPTIONS
.PP
Monolithic options starting with "\fB--\fR" are used to modify behavior of terminal
(if supported by terminal and its entry):
.PP
.PD 0
.IP \(bu 4
\fB--app-id=\fR\fIapp_id\fR: set app-id (Wayland) or class (X11).\&
.IP \(bu 4
\fB--title=\fR\fItitle\fR: set tile of terminal.\&
.IP \(bu 4
\fB--dir=\fR\fIworkdir\fR: set workdir of terminal.\&
.IP \(bu 4
\fB--hold\fR: instruct terminal to hold after command ends.\&
.PD
.PP
Options for printing data instead of executing terminal:
.PP
.PD 0
.IP \(bu 4
\fB--print-id\fR: print selected Desktop Entry ID.\& Action is appended delimited
by "\fB:\fR".\&
.IP \(bu 4
\fB--print-path\fR: print path to selected Desktop Entry.\& Action is appended
delimited by "\fB:\fR".\&
.IP \(bu 4
\fB--print-content\fR: print content of selected Desktop Entry.\& Conflicts with
\fB--print-cmd\fR.\&
.IP \(bu 4
\fB--print-cmd\fR[\fB=\fR\fIprintf_sequence\fR]: print resulting command line, delimited by
given printf sequence, "\fB\en\fR" by default.\& If sequence is "\fB\en\fR", output is
also terminated with a newline.\&
.IP \(bu 4
\fB--print-delimiter=\fR\fIprintf_sequence\fR: printf sequenc to be used as the
delimiterprint between multiple requested statements, "\fB\en\fR" by default.\&
If sequence is "\fB\en\fR", overall output is also terminated with a newline
(without duplication in case command output already terminated on a newline).\&
.PD
.PP
Selected data is printed in order:
.PP
.PD 0
.IP \(bu 4
id
.IP \(bu 4
path
.IP \(bu 4
content
.IP \(bu 4
cmd
.PD
.PP
.SH CONFIGURATION
.PP
Preferred terminals are configured by listing them in config files
named \fI${desktop}\fR\fB-xdg-terminals.\&list\fR or \fBxdg-terminals.\&list\fR
placed in XDG Config hierarchy.\&
.PP
\fI${desktop}\fR here is a lowercased string that is matched (case-insensitively)
against items of \fI${XDG_CURRENT_DESKTOP}\fR (a colon-separated list of names for
the current DE) in order of decreasing priority.\&
.PP
The file is a simple newline-separated list.\& Empty lines and lines starting with
"\fB#\fR" are ignored, dangling whitespaces are trimmed.\&
.PP
Terminals are listed by their Desktop Entry ID:
.PP
.RS 4
\fIterminal\fR\fB.\&desktop\fR
.PP
.RE
Optionally with Action ID suffixed via "\fB:\fR":
.PP
.RS 4
\fIterminal\fR\fB.\&desktop\fR:\fIaction\fR
.PP
.RE
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 \fI${XDG_CURRENT_DESKTOP}\fR.\& Unprefixed files parsed last in each dir.\&
.PP
The first listed, found, and valid Desktop Entry is used.\&
.PP
Otherwise fallback to the first found and valid Desktop Entry is performed.\&
.PP
Entries can be excluded from fallback by listing their ID prefixed with "\fB-\fR":
.PP
.RS 4
\fB-\fR\fIterminal\fR\fB.\&desktop\fR
.PP
.RE
Prefixing entry with "\fB+\fR" will prevent it from later exclusion (first
encountered directive wins):
.PP
.RS 4
\fB+\fR\fIterminal\fR\fB.\&desktop\fR
.PP
.RE
Special directives understood by this implementation (the first encountered
directive is used):
.PP
.RS 4
\fB/enable_cache\fR, \fB/disable_cache\fR
.PP
.RE
The cache feature allows storing selected terminal command line in
\fI${XDG_CACHE_HOME}\fR 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).\&
.PP
.RS 4
\fB/execarg_compat\fR, \fB/execarg_strict\fR
.PP
.RE
Compat mode (currently enabled by default) allows support for legacy
\fB[X-]ExecArg\fR key and allows entries without execution argument, providing \fI-e\fR
default.\&
.PP
.RS 4
\fB/execarg_default:\fR\fIentry.\&desktop\fR\fB:\fR\fIarg\fR
.PP
.RE
Customize defaults for execution arguments of specific terminal entries (only in
compat mode).\&
.PP
.SH FILES
.PP
Default paths for configuration files (in order of decreasing priority):
.PP
In \fI${XDG_CONFIG_HOME}\fR:
.PD 0
.IP \(bu 4
\fI${HOME}\fR\fB/.\&config/\fR\fI${desktop}\fR\fB-xdg-terminals.\&list\fR
.IP \(bu 4
\fI${HOME}\fR\fB/.\&config/xdg-terminals.\&list\fR
.PD
.PP
In \fI${XDG_CONFIG_DIRS}\fR:
.PD 0
.IP \(bu 4
\fB/etc/xdg/\fR\fI${desktop}\fR\fB-xdg-terminals.\&list\fR
.IP \(bu 4
\fB/etc/xdg/xdg-terminals.\&list\fR
.PD
.PP
In \fI${XDG_DATA_DIRS}\fR:
.PD 0
.IP \(bu 4
\fB/usr/share/xdg-terminal-exec/\fR\fI${desktop}\fR\fB-xdg-terminals.\&list\fR
.IP \(bu 4
\fB/usr/share/xdg-terminal-exec/xdg-terminals.\&list\fR
.PD
.PP
Default directories for Desktop Entries (in order of decreasing priority):
.PP
in \fI${XDG_DATA_HOME}\fR:
.PD 0
.IP \(bu 4
\fI${HOME}\fR\fB/.\&local/share/applications/\fR
.PD
.PP
in \fI${XDG_DATA_DIRS}\fR:
.PD 0
.IP \(bu 4
\fB/usr/local/share/applications/\fR
.IP \(bu 4
\fB/usr/share/applications/\fR
.PD
.PP
Cache file:
.PD 0
.IP \(bu 4
\fI${XDG_CACHE_HOME}\fR\fB/xdg-terminal-exec\fR
.PD
.PP
.SH ENVIRONMENT
.PP
\fBXTE_CACHE_ENABLED\fR (truthy or falsy value)
.RS 4
Enable or disable cache feature.\&
.PP
.RE
\fBXTE_DEBUG\fR, \fBDEBUG\fR (truthy or falsy value)
.RS 4
Print debug info to stderr.\&
.PP
.RE
.SH EXTERNAL LINKS
.PP
Proposal PR:
.PP
https://gitlab.\&freedesktop.\&org/terminal-wg/specifications/-/merge_requests/3/diffs
.PP
XDG Base Directory Spec:
.PP
https://specifications.\&freedesktop.\&org/basedir-spec/latest/
.PP
XDG Desktop Entry Spec:
.PP
https://specifications.\&freedesktop.\&org/desktop-entry-spec/latest/
.PP
Desktop Entry ID:
.PP
https://specifications.\&freedesktop.\&org/desktop-entry-spec/latest/ar01s02.\&html#desktop-file-id
.PP
Desktop Entry Action ID:
.PP
https://specifications.\&freedesktop.\&org/desktop-entry-spec/latest/ar01s11.\&html
.PP
.SH AUTHORS
.PP
Vladimir-csp (https://github.\&com/Vladimir-csp, https://gitlab.\&freedesktop.\&org/Vladimir-csp)
.PP
Thanks to Nathan Teodosio (https://github.\&com/nteodosio) for jump-starting the creation of this manpage.\&
