J4-DMENU-DESKTOP(1)

🎀 NAME 🎀

j4-dmenu-desktop — the fast desktop menu, bestie 💅 (it lives in the General Commands Manual, section 1, and it's literally iconic)

---

✨ SYNOPSIS ✨

j4-dmenu-desktop [OPTIONS]

---

💖 DESCRIPTION 💖

j4-dmenu-desktop is a faster replacement for i3-dmenu-desktop. No cap. 🏃♀️💨

Its whole purpose, its main character moment, is to go find .desktop files and offer you a menu so you can start an application using dmenu. Slay. 🦋

The arguments are as follows:

• -b, --display-binary — shows the binary name after every entry. Off by default, so don't expect it unless you ask.
• -f, --display-binary-base — shows the basename of the binary name after every entry. Also off by default.
• -d, --dmenu command — this is the command used to invoke dmenu. It gets executed with your shell ($SHELL) or with /bin/sh.
• --no-exec — do not execute the command you picked. Just send it to stdout instead. Very "look but don't touch" of it.
• --no-generic — don't include the generic name of desktop entries.
• -t, --term command — sets the terminal emulator used to start terminal apps.
• --term-mode mode — tells j4-dmenu-desktop how it should execute the terminal emulator. This flag also changes the default value of the --term flag. 👀

Possible values are: default | xterm | alacritty | kitty | terminator | gnome-terminal | custom

See TERM MODE below for the whole tea. 🫖

• --usage-log file — has to point at a read-writeable file (it'll create it if it's not there). In this mode, entries get sorted by usage frequency. Algorithm behavior, honestly.
• --prune-bad-usage-log-entries — removes names marked in the usage log that j4-dmenu-desktop couldn't find a desktop file for. This can happen when an app marked in the usage log no longer exists because it got uninstalled. 💀
• -x, --use-xdg-de — turns on reading $XDG_CURRENT_DESKTOP to figure out the desktop environment.
• --wait-on path — has to point to a path where a file can be created. In this mode no menu is shown. Instead the program waits for path to be written to (use echo > path). Every single time that happens, a menu gets shown. Desktop files are parsed ahead of time. And performing echo -n q > path will exit the program. That's the quit code, iykyk. ✨
• --wrapper wrapper — a wrapper binary. Heads up: using --wrapper "i3 exec" and --wrapper "sway exec" is deprecated — use --i3-ipc instead.
• -I, --i3-ipc — executes desktop entries through i3 IPC or Sway IPC. Requires either i3 or Sway to actually be running.
• --skip-i3-exec-check — disables the check for --wrapper "i3 exec" or --wrapper "sway exec". j4-dmenu-desktop has direct support for i3/Sway through the -I flag, which should be used instead of the --wrapper option. j4-dmenu-desktop detects this and exits. This flag overrides that behaviour. It's giving "I know what I'm doing, let me cook." 🍓
• -i, --case-insensitive — sorts applications case insensitively.
• -v — be more verbose. Specified once → INFO is used. Twice → DEBUG is used. See LOG LEVELS. 🗣️
• --log-level ERROR | WARNING | INFO | DEBUG — a more explicit version of -v. This flag takes precedence over -v.
• --log-file file — specify a log file. file will be truncated. By default, the INFO loglevel is used.
• --log-file-level ERROR | WARNING | INFO | DEBUG — set the file log level.
• --desktop-file-quirks ARGS — modifies j4-dmenu-desktop's desktop file parsing mechanism to accommodate desktop files that don't conform to the Desktop Entry Specification. Several modes may be specified. They shall be separated by a comma (,). Each mode has a nomode counterpart, which disables the named mode. To disable all modes, use --strict-parsing. A warning is printed when a desktop file makes use of an enabled quirk. ARGS can contain the following modes:
  • wine — tolerate invalid escape codes (such as escaping a space to disable separating arguments) in the Exec key of desktop files. Enabled by default.
  • multispace — tolerate the usage of several spaces to separate arguments in the Exec key of desktop files. Useful for desktop files generated by distrobox. Enabled by default.

If this flag is specified multiple times, only the last one takes effect. They are not merged nor combined in any way. 🚫

This flag is mutually exclusive with --strict-parsing.

• --strict-parsing — strictly adhere to the Desktop Entry Specification while parsing desktop files. Not enabled by default.

This flag is mutually exclusive with --desktop-file-quirks.

• --version — display program version.
• -h, --help — display help message.

---

🌈 LOG LEVELS 🌈

Some arguments support setting the log level. j4-dmenu-desktop uses the following log levels: ERROR, WARNING, INFO and DEBUG. The WARNING (and ERROR) loglevels are displayed by default. Lower loglevels automatically enable higher ones. It's a ladder, bestie. Climb it. 🪜

---

🧚 TERM MODE 🧚

There are several modes available for the --term-mode flag:

• default — the default mode. A temporary shell script is created containing the chosen command. The script deletes itself upon execution — j4-dmenu-desktop never deletes it itself. It sets the title of the terminal emulator using OSC escape sequences (see console_codes(4)). Terminal emulator is executed as follows:

[terminal emulator] -e [generated temporary script]

Other modes should be preferred. This approach is universal but fragile. 🫣

Default value of --term is i3-sensible-terminal.

• xterm — use the xterm calling convention:

[terminal emulator] -title [desktop app Name] -e [command line]

Default value of --term is xterm. Other compatible terminal emulators include: rxvt-unicode.

• alacritty — use the alacritty calling convention:

[terminal emulator] -T [desktop app Name] -e [command line]

Default value of --term is alacritty. Other compatible terminal emulators include: st, foot.

• kitty — use the kitty calling convention:

[terminal emulator] -T [desktop app Name] [command line]

Default value of --term is kitty. Other compatible terminal emulators include: foot.

• terminator — use the terminator calling convention:

[terminal emulator] -T [desktop app Name] -x [command line]

Default value of --term is terminator. Other compatible terminal emulators include: xfce4-terminal.

• gnome-terminal — use the gnome-terminal calling convention:

[terminal emulator] --title [desktop app Name] -- [command line]

Default value of --term is gnome-terminal.

• custom — allow for completely custom handling of --term. When --term-mode custom is passed, an alternative system for handling --term is used. It is handled as a list of arguments separated by space ( ). No other whitespace characters act as an argument separator (this behavior differs from the shell). 👑

Multiple consecutive space characters will be treated as a single space (except for escaped spaces). Leading and trailing spaces in --term will be ignored. This means that it is not possible to pass zero-length arguments to --term.

The contents of --term are not executed through a shell. This means shell constructs like redirection, && and || chaining and more will not work. If you need this, you can either create a wrapper shell script and call it from --term, or you can call /bin/sh -c or some other shell directly from --term (although using a wrapper script should be preferred, because it is clearer and simpler to use).

The following placeholders are recognised:

• {name} — name of desktop app. Useful for setting the title.
• {cmdline@} — command line to be executed, expanded as separate arguments. This must be an independent argument; j4-dmenu-desktop --term-mode custom --term "-e={cmdline@}" is invalid.
• {cmdline*} — command line to be executed, expanded as a single argument. {cmdline@} should be preferred over {cmdline*}. Arguments will be escaped; contents of {cmdline*} can be passed to /bin/sh -c safely.
• {script} — filename of a script generated by j4-dmenu-desktop. This is the same script used by --term-mode default. The script will be generated only if this placeholder is specified at least once in --term. The script sets the terminal title itself, so it shouldn't be necessary to set it manually.

{cmdline@} and {cmdline*} should be preferred over {script}.

The following escape sequences are recognised:

• \\ — literal \ character.
• \{ — literal { character.
• \ — (backslash with space) do not handle the following space as an argument separator.

Undefined escape sequences and placeholders will result in an error message and program termination. 🚨

Default value of --term is same as of default term mode.

This is how other modes look when written using custom mode:

• default — j4-dmenu-desktop --term-mode custom --term "i3-sensible-terminal -e {script}"
• xterm — j4-dmenu-desktop --term-mode custom --term "xterm -title {name} -e {cmdline@}"
• alacritty — j4-dmenu-desktop --term-mode custom --term "alacritty -T {name} -e {cmdline@}"
• kitty — j4-dmenu-desktop --term-mode custom --term "kitty -T {name} {cmdline@}"
• terminator — j4-dmenu-desktop --term-mode custom --term "terminator -T {name} -x {cmdline@}"
• gnome-terminal — j4-dmenu-desktop --term-mode custom --term "gnome-terminal --title {name} -- {cmdline@}"

This is how the deprecated -e flag of gnome-terminal could be used:

j4-dmenu-desktop --term-mode custom --term "gnome-terminal --title {name} -e {cmdline*}"

This is how placeholders can be escaped:

j4-dmenu-desktop --term-mode custom --term "echo \{name}\
\{cmdline*}"

okay so real talk bestie: --term here gets two arguments — echo and {name} {cmdline*} — and no placeholders get replaced, like, none, zero, the placeholder fairy did not visit. and lowkey the whole reason is that backslash: if that second \ had not been passed, j4-dmenu-desktop would've seen three arguments instead of two. the way that one character is carrying the entire vibe 😭

---

🌿 ENVIRONMENT 🌿

the vibes your shell hands over. these are the variables it actually cares about 💅

• I3SOCK — this one overwrites the i3/Sway IPC socket path. that's it, that's the whole job, and it slays at it ✨
• XDG_DATA_HOME — the primary directory where desktop files live. main character directory energy 👑
• XDG_DATA_DIRS — the additional directories that also contain desktop files. the supporting cast 🫶
• XDG_CURRENT_DESKTOP — the current desktop environment, used for enabling/disabling desktop-environment-dependent desktop files. ⚠️ heads up though: this one must be enabled by --use-xdg-de — it doesn't just do stuff on its own, it needs permission fr fr.

and ngl there's more: standard environmental variables for locales are acknowledged in addition to the ones listed above 🦋 the exact environmental variables used are implementation-dependent, but setting LC_MESSAGES, LC_ALL or LANG should generally work. no cap.

---

👀 SEE ALSO 👀

• https://github.com/enkore/j4-dmenu-desktop

go click it, it's giving source-code-and-issues realness 💖

---

📜 COPYRIGHT 📜

Copyright (C) 2013 enkore <public+j4-dmenu-desktop@enkore.de>

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

💀 not me actually reading the warranty disclaimer — it is all caps for a reason bestie, no warranty, no promises, we are simply vibing 🫶

---

and that's a wrap on the whole page, bestie!! 🎀 this one's from Debian, dated January 10, 2024, and it lives under the name J4-DMENU-DESKTOP(1) in the manual section 1 ✨ go forth and launch apps, you absolute icon 💅🌸