JOME(1)

👑 jome(1) — a keyboard centric desktop emoji picker 👑

🌸 NAME 🌸

jome — a keyboard centric desktop emoji picker. That's the whole vibe, bestie. 💅

---

✨ SYNOPSIS ✨

jome [-f cp [-p PREFIX]] [-n] [-V] [-t (L | ML | M | MD | D)]
     [-c CMD] [-b] [-q | -s NAME]
     [-d] [-C] [-L] [-R] [-k]
     [-w (16 | 24 | 32 | 40 | 48)] [-P] [-H COUNT]

---

💖 DESCRIPTION 💖

jome (joh·mee) is a keyboard centric emoji picker desktop application.

jome’s sole purpose is to help you pick an emoji. In other words, it doesn’t really care what you do with the chosen emoji afterwards: you can leverage tools such as xdotool(1) to “type” it or xsel(1) to copy it to the clipboard. See the “Type the accepted emoji” section below and the -c option for a starting point.

When you accept an emoji (with the keyboard or with the mouse), jome prints the UTF-8 emoji or the Unicode codepoints (see the -f option), with an optional prefix (see the -p option) for each codepoint, to the standard output.

Additionally, jome can:

• Copy the UTF-8 emoji or the Unicode codepoints to the clipboard. See the -b option.
• Execute a custom command which sends the UTF-8 emoji or the Unicode codepoints, with an optional prefix for each codepoint, as its last argument(s). See the -c option.
• Send the UTF-8 emoji or the Unicode codepoints, with an optional prefix for each codepoint, in response to a client which requested picking an emoji. See the “Server mode” section below.

If you close the window (you can press Escape or Ctrl+C to do this), then jome prints nothing to the standard output, executes nothing, and exits with status 1.

If you don’t start jome in server mode (-s option) and you don’t specify the -q option, then jome immediately exits with status 0 after you accept an emoji or close the window.

🎀 Graphical interface 🎀

There are four sections:

Find box (top)

Input box where you can type a query to find emojis.

Emoji grid

All emojis (with an empty find box) or find results.

When there’s at least one emoji, there’s always a selected emoji with a square box around it.

Click an emoji to accept it. Press Shift when clicking to not print VS-16 codepoints (see the -V option).

Hover an emoji to update the bottom emoji info text temporarily.

Make the background behind emojis dark with the -d option.

Hide the category labels with the -L option.

Hide the “Recent” category with the -R option.

Category list (right)

List of available categories.

When all emojis are viewed (the find box is empty), click a category name to scroll to this emoji category.

The first category, “Recent”, is a special category with the recently accepted emojis.

Override the maximum number of recently accepted emojis with the -H option.

Hide the “Recent” category with the -R option.

Hide the whole category list with the -C option.

Emoji info text (bottom)

Name, Unicode codepoints, Emoji standard version, and keywords of the selected or hovered emoji.

Hide the keyword list with the -k option.

🔍 Find emojis 🔍

The power of jome is its find box (top).

When you launch jome, the find box is focused, and it should stay focused unless you browse emojis manually with the intention of accepting one with the mouse.

The format of a query is one of:

• TERMS
• CAT/
• CAT/TERMS
• CODEPOINT
• CAT/CODEPOINT

where:

• CAT — Partial name of categories in which to find.
• TERMS — Space-separated list of search terms. For an emoji to be part of the results, its name and keywords must contain ALL the searched terms.
• CODEPOINT — A single Unicode codepoint using the standard U+ABCD notation.

Everything is case-insensitive.

🦋 Select and accept an emoji 🦋

To select an emoji, use the following keys:

• ←, →, ↑, ↓ — Go left/right/up/down.
• Ctrl+←, Ctrl+→ — Go left/right five emojis.
• Page ↑, Page ↓ — Go up/down ten rows.
• Home — Go to the first emoji.
• End — Go to the last emoji.

To accept the selected emoji, press:

• Enter — Accept the selected emoji with, if applicable:
  • Without the -t option — No skin tone (“yellow”).
  • With the -t option — The default skin tone (value of -t).
• Shift+Enter — Like Enter, but do not print VS-16 codepoints. See the -V option option.
• F1 to F5 — If the selected emoji supports skin tones, accept the selected emoji with a light, medium-light, medium, medium-dark, or dark skin tone, overriding the -t option (if any).
• Shift+F1 to Shift+F5 — Like F1 to F5, but do not print VS-16 codepoints. See the -V option option.

To cancel, press Escape or Ctrl+C, or close the window.

🌈 Go to Emojipedia page 🌈

To go to the Emojipedia ⟨https://emojipedia.org/⟩ page of the selected emoji, press F12.

To go to the Emojipedia page of any emoji with the mouse, right-click it and click “Go to Emojipedia page”.

🍓 User-defined emoji keywords 🍓

You can either replace or augment the built-in list of keywords which jome searches when you find emojis.

To set user-defined keywords, create an emojis.json file within ~/.config/jome/.

emojis.json must contain a JSON object where keys are emojis and values are objects. Each value may contain one of:

• keywords — An array of keywords which replaces the built-in keywords entirely for this emoji.
• extra-keywords — An array of keywords which augments either the built-in keywords or the keywords of the keywords entry for this emoji.

Example:

{
  "🍁": {
    "extra-keywords": ["canada", "laurentides"]
  },
  "😃": {
    "keywords": ["yay", "hourra"]
  },
  "🚬": {
    "extra-keywords": ["claude poirier"]
  },
  "🫚": {
    "extra-keywords": ["canada dry", "martin deschamps"]
  }
}

👑 Server mode 👑

jome features a server mode to avoid creating a process (a Qt window can be quite long to create) every time you need to pick an emoji. With this mode, you can view the jome window instantaneously.

To start jome in server mode, use the -s option to specify the server name:

$ jome -s mein-server

This creates a local server named mein-server. On Unix, it creates the socket file /tmp/mein-server.

Important: On Unix, the server mode won’t work if the socket file already exists. Remove the file before you start jome in server mode:

$ rm -f /tmp/mein-server
$ jome -s mein-server

When jome starts in server mode, it doesn’t show its window. Instead, it waits for a command sent by the client, jome-ctl(1). To show the window:

$ jome-ctl mein-server

When you accept an emoji, jome-ctl(1) prints what jome also prints to the standard output and quits with exit code 0. Therefore, the options passed to jome(1) control the output format of jome-ctl(1).

If you cancel jome (press Escape or Ctrl+C, or close the window), jome-ctl(1) prints nothing and returns with exit code 1.

In server mode, jome doesn’t quit once you accept an emoji or cancel: it hides the window and keeps listening. To make it quits gracefully, which also removes the socket file:

$ jome-ctl mein-server quit

You don’t need to use what jome-ctl(1) prints to the standard output. You can use jome in server mode with the -c option to make jome execute a command itself. For example:

$ rm -f /tmp/mein-server
$ jome -s mein-server -c 'xdotool type'

Then, bind a keyboard shortcut to:

$ jome-ctl mein-server

💜 Type the accepted emoji 💜

Here are Bash scripts to type the accepted emoji with xdotool(1).

Direct mode

With xdotool key

#!/usr/bin/bash

codepoints=$(jome -f cp -p U)

if (($? != 0)); then
    exit 1
fi

xdotool key --delay 20 "$codepoints"

With xdotool type

#!/usr/bin/bash

emoji=$(jome)

if (($? != 0)); then
    exit 1
fi

xdotool type "$emoji"

Server mode

With xdotool key

#!/usr/bin/bash

socket_name=jome.socket.$(id -u)

if [[ ! -e "/tmp/$socket_name" ]]; then
    jome -s "$socket_name" -n -w48 -f cp -p U & disown

    until [[ -e "/tmp/$socket_name" ]]; do
        sleep .1
    done
fi

codepoints=$(jome-ctl "$socket_name")

if (($? == 0)); then
    sleep .02
    xdotool key --delay 20 "$codepoints"
fi

With xdotool type

#!/usr/bin/bash

socket_name=jome.socket.$(id -u)

if [[ ! -e "/tmp/$socket_name" ]]; then
    jome -s "$socket_name" -n -w48 & disown

    until [[ -e "/tmp/$socket_name" ]]; do
        sleep .1
    done
fi

emoji=$(jome-ctl "$socket_name")

if (($? == 0)); then
    sleep .02
    xdotool type "$emoji"
fi

✨ OPTIONS ✨

Okay bestie, this is the part where you tell jome how to talk, how to act, and how to look. Every flag is a little lewk. 💅

💖 Output 💖

• -f FMT — choose the output format, FMT, and here are your options:
  • utf-8 (the default) — gives you straight-up UTF-8 emoji. 🦋
  • cp — spits out space-separated Unicode codepoints in hexadecimal. ✨ Example:

1f645 200d 2642 fe0f

You can prepend a prefix to each codepoint with the -p option.

• -p PREFIX — set the prefix that gets prepended to each Unicode codepoint when you use -f cp. For example, with -f cp and -p U+:

U+1f645 U+200d U+2642 U+fe0f

• -n — do not print a newline after printing the emoji or codepoints. No extra line break, periodt. 🎀
• -V — do not print Variation Selector-16 ⟨https://emojipedia.org/variation-selector-16⟩ (VS-16) codepoints. So what is VS-16? It's a suffix codepoint that says “hey, display the character before me with emoji presentation.” Like, ♥ (which predates Unicode emojis) plus VS-16 becomes a red heart. But some apps and fonts are not fans of VS-16, so this flag is your escape hatch.
• -t TONE — set the default skin tone to TONE instead of none:
  • L — Light.
  • ML — Medium-light.
  • M — Medium.
  • MD — Medium-dark.
  • D — Dark. The F1 to F5 keys still acept an emoji with a specific skin tone. 💅

🎬 Action 🎬

• -c CMD — when you accept an emoji, run the command CMD 20 ms after the jome window closes. jome interprets CMD the way a shell does, so you can include arguments too. CMD receives the UTF-8 emoji or the Unicode codepoints (depending on the -f option) with their optional prefix as its last argument(s). Examples with xdotool:

$ jome -c 'xdotool type'
$ jome -f cp -p U -c 'xdotool key --delay 20'

• -b — when you accept an emoji, copy the UTF-8 emoji or the Unicode codepoints (depending on the -f option) to the clipboard.

Warning — This uses QClipboard and is known not to always work, depending on your window manager. 💀

• -q — do not quit when you accept an emoji. By default, when you accept an emoji (with the keyboard or with the mouse), jome does this little routine:
  1. Prints the accept emoji or its codepoints to the standard output.
  2. Hides its window.
  3. Optional: Copies the accept emoji/codepoints to the clipboard (see the -b option).
  4. Optional: Executes a command (see the -c option) after 20 ms.
  5. If not running in server mode, quits (see the -s option). With the -q option, jome doesn’t hide its window and doesn’t quit when you accept an emoji, so you can make it print multiple emojis and/or execute a command multiple time with multiple emojis without restarting the application. 🔥 You cannot specify the -q and -s options together.
• -s NAME — start jome in server mode and set the server name to NAME. On Unix, this creates the socket file /tmp/NAME which must NOT exist before you start jome. ⚠️ You cannot specify the -s and -q options together.

🌸 User interface 🌸

• -d — use a dark background for emojis.
• -C — hide the category list.
• -L — hide the category labels in the emoji grid.
• -R — hide the “Recent” category.
• -r — include the recently accepted emojis in the results when finding emojis. In this case, jome shows the recently accepted emojis first within the result grid. 👑
• -k — hide the keyword list.
• -w WIDTH — set the width of individual emojis to WIDTH pixels, amongst 16, 24, 32 (default), 40, or 48.
• -P PERIOD — set the flashing period of the selection box to PERIOD ms (greater than or equal to 32). The selection box doesn’t flash by default.
• -H COUNT — set the maximum number of recently accepted emojis to COUNT instead of 30.

📁 FILES 📁

• ~/.config/jome/emojis.json — User-defined emoji keywords. See the “User-defined emoji keywords” section above.

🚪 EXIT STATUS 🚪

0 when you accept an emoji or 1 otherwise. Simple as that.

👑 ABOUT 👑

jome was originally written by and is maintained by, as of jome 1.5.0, Philippe Proulx (eepp).

GitHub project: ⟨https://github.com/eepp/jome⟩. 🦋

👀 SEE ALSO 👀

jome-ctl(1) — go check it out, bestie. 💖

---

And that's the page, bestie! This one is JOME(1), source JOME, dated 14 April 2025. Go forth and emoji. 💖✨