tym(1)

📦
version 3.7.0 · 2 versions
, in nixpkgs unstable

💅 tym(1) — the tiny terminal emulator that's lowkey iconic

okay so bestie, welcome to tym — a tiny VTE-based terminal emulator, which is configurable by Lua. yes, Lua. she's cute, she's small, she's giving main character energy ✨

✨ DESCRIPTION ✨

tym is a tiny VTE-based terminal emulator, which configurable by Lua. that's it, that's the vibe 🫶

🌸 SYNOPSIS 🌸

tym [OPTIONS]

🎀 OPTIONS 🎀

  • -h, --help — Show help message. (the classic "what does anything do" button 💖)
  • -v, --version — Show version.
  • -u, --use=<PATH> — Use <PATH> instead of default config file.
  • -t, --theme=<PATH> — Use <PATH> instead of default theme file.
  • --cwd=<PATH> — Use <PATH> as the terminal's working directory. Must be an absolute path — no relativeness allowed, she's strict about that fr fr.
  • --<OPTION>=<VALUE> — Replace <OPTION> config option, where <OPTION> is a config option and <VALUE> is a value of its option. See CONFIGURATION for more information about config options. 👑

🦋 AVAILABLE OPTIONS 🦋

the string girlies 🎀

  • shell — Type: string Default: $SHELL → vte_get_user_shell() → /bin/sh Shell to execute.
  • title — Type: string Default: 'tym' Initial window title.
  • font — Type: string Default: '' (empty string) You can specify it like 'FAMILY-LIST [SIZE]', for example 'Ubuntu Mono 12'. The value is parsed by pango_font_description_from_string(). If you set empty string, the system default fixed width font will be used.
  • icon — Type: string Default: 'terminal' Name of icon. cf. https://developer.gnome.org/icon-naming-spec/.
  • cursor_shape — Type: string Default: 'system' 'block', 'ibeam' or 'underline' are available.
  • cursor_blink_mode — Type: string Default: 'system' 'system', 'on' or 'off' are available.
  • term — Type: string Default: 'xterm-256color' Default value of $TERM.
  • role — Type: string Default: '' Unique identifier for the window. If empty string set, no value set. cf. gtk_window_set_role()
  • cjk_width — Type: string Default: 'narrow' 'narrow' or 'wide' are available.
  • uri_schemes — Type: string Default: 'http https file mailto' Space-separated list of URI schemes to be highlighted and clickable. Specify empty string to disable highlighting. Specify '*' to accept any strings valid as schemes (according to RFC 3986).

the numbers girlies 🔢

  • width — Type: integer Default: 80 Initial columns.
  • height — Type: integer Default: 22 Initial rows.
  • adding_horizontal — Type: integer Default: 80 Horizontal padding.
  • adding_vertical — Type: integer Default: 80 Vertical padding.

the boolean girlies 🍓

  • ignore_default_keymap — Type: boolean Default: false If it is provided, the default keymap will not be used.
  • autohide — Type: boolean Default: false If it is provided, mouse cursor will be hidden when you presses a key.
  • bold_is_bright — Type: boolean Default: false If it is provided, make bold texts bright..
  • silent — Type: boolean Default: false If it is provided, beep does not sound when bell sequence is sent.
  • osc_clipboard — Type: boolean Default: false If it is provided, the application can write the clipboard by setting the vte.ext.tym.clipboard termprop to base64-encoded UTF-8 text, up to 2048 bytes once decoded. It requires VTE 0.78 or later — check your version bestie, no cap 🙈.

misc 🧚

  • scrollback_length — Type: integer Default: 512 If it is provided, the length of scrollback buffer is resized.

the colour situation 🌈

  • color_window_background — Type: ing Default: '' Color of the terminal window. It is seen when padding_horizontal padding_vertical is not 0. If you specify 'NONE', the window background will not be drawn.
not me noticing the type literally says ing in the page 😭 that's what it says, I don't make the rules, I just report them 💀
  • color_foreground
  • color_background
  • color_cursor
  • color_cursor_foreground
  • color_highlight
  • color_highlight_foreground
  • color_bold
  • color_0 .. color_15 — Type: string Default: '' (empty string) You can specify standard color string such as '#f00', '#ff0000', 'rgba(22, 24, 33, 0.7)', or 'red'. It will be parsed by gdk_rgba_parse(). If you set empty string, the VTE default color will be used. If you set 'NONE' for color_background, the terminal background will not be drawn.

👑 DEFAULT KEYBINDINGS 👑

the starter pack, the OG trio 💅

  • Ctrl+Shift+c — Copy selection to clipboard
  • Ctrl+Shift+v — Paste from clipboard
  • Ctrl+Shift+r — Reload config file

💜 CONFIGURATION 💜

When $XDG_CONFIG_HOME/tym/config.lua exists, it is executed. Here is an example — obsessed with how readable this is 🫶

local tym = require('tym')
tym.set('font', 'DejaVu Sans Mono 11')
tym.set_config({
  shell = '/usr/bin/fish',
  cursor = 'underline',
  autohide = true,
  color_foreground = 'red',
})
tym.set_keymap('<Ctrl><Shift>o', function()
  local h = tym.get('height')
  tym.set('height', h + 1)
  tym.apply() -- needed for applying config value
  tym.notify('Set window height :' .. h)
end)
tym.set_keymaps({
  ['<Ctrl><Shift>y'] = function()
    tym.reload()
    tym.notify('reload config')
  end,
  ['<Ctrl><Shift>v'] = function()
    tym.notify("Overwrite pasting event")
  end,
})

⭐ LUA API ⭐

the whole toolkit, laid out for you bestie 🎀

tym.get(key)

Returns: any Get config value.

tym.set(key, value)

Returns: void Get config value.

yep, it literally says "Get" here in the page — I'm just the messenger 🙈 don't come for me

tym.get_config()

Returns: table Get config table.

tym.set_config(table)

Returns: void Set config by table.

tym.reset_config()

Returns: void Reset config to default.

tym.set_keymap(accelerator, func)

Returns: void Set keymap. accelerator must be in a format parsable by gtk_accelerator_parse().

tym.set_keymaps(table)

Returns: void Set keymaps by table.

tym.reset_keymaps()

Returns: void Reset custom keymaps.

tym.send_key(accelerator)

Returns: void Send key press event.

tym.reload()

Returns: void Reload config file and theme file.

tym.reload_theme()

Returns: void Reload theme file.

tym.apply()

Returns: void Apply config to app.

tym.put(text)

Returns: void Feed text.

tym.bell()

Returns: void Sound bell. 🔔

tym.notify(message, title = 'tym')

Returns: void Show desktop notification.

tym.copy()

Returns: void Copy current selection.

tym.paste()

Returns: void Paste clipboard.

tym.get_version()

Returns: string Get version string.

tym.get_config_path()

Returns: string Get path of config file currently being read.

tym.get_theme_path()

Returns: string Get path of theme file currently being read.

🌸 THEME CUSTOMIZATION 🌸

When $XDG_CONFIG_HOME/tym/theme.lua exists, it is executed. Here is an example — look at that palette, she ate 🔥

local fg = '#d2d4de'
local bg = '#161821'
return {
  color_background = bg,
  color_foreground = fg,
  color_0  = '#161821',
  color_1  = '#e27878',
  -- SNIP
  color_14 = '#95c4ce',
  color_15 = '#d2d4de',
}

You need to return table within global context. no cap, that part actually matters ✨

okay that's the whole page bestie, you're officially a tym expert now 💖 go forth and make your terminal gorgeous 🌈💅

sign-off time: this is version 3.7.0, dated 2026-10-22, and the manual itself is tym(1) — iykyk 🦋
📦 where this page comes from