SUBTLER(1)

📦 version 0.11.3224-xi, in debian bookworm, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 SUBTLER 💖

okay bestie, gather round, because this is subtler — a commandline interface for subtle. yes THE subtle. no cap. 🎀

✨ SYNOPSIS ✨

subtler [GENERIC|MODIFIER] GROUP ACTION [ARG1] [ARG2]

🌸 DESCRIPTION 🌸

so subtler is a commandline tool that lets you interact with an EWMH/NetWM compatible window manager — and especially with subtle(1) — straight from your shell. it's giving terminal-to-window-manager bestie energy fr fr 🦋

the arguments of subtler are quite complex and allow a variety of spellings and different numbers of arguments. most of the commands require at least one argument and return output of following format:

🫶 FORMAT 🫶

📥 INPUT

DISPLAY :<display number>
ID <number>
GEOMETRY <x>x<y>+<width>+<height>
NAME <string|number>
DATA <string|number>
PATTERN matching works either via plaintext, regex(7), id or window id if applicable. if a pattern matches more than once ALL matches are used. periodt 💅

if the PATTERN is - subtler will read from stdin.

📤 OUTPUT

Client listing <window id> <visibility> <view id> <geometry> <gravity> <flags> <instance name> (<class name>)
Gravity listing <gravity id> <geometry>
Screen listing <screen id> <geometry>
Tag listing <tag name>
Tray listing <window id> <instance name> (<class name>)
View listing <window id> <visibility> <view id> <view name>

🔍 FIELDS 🔍

<window id> — Numeric (hex) id (e.g. 0xa00009)
<visibility> — - = not visible, * = visible
<view id> — Numeric id (e.g. 5)
<geometry> — x x y + width + height
<flags> — - = not set, + = fullscreen, ^ = float, * = stick, ~ = resize, = = zaphod, ! = fixed
<instance name> — Window instance/resource name
<class name> — Window class name
<gravity id> — Numeric id of gravity (e.g. 2)
<screen id> — Numeric id of a screen (e.g. 1)
<tag name> — Name of a tag (e.g. terms)

🌈 OPTIONS 🌈

🌟 GENERIC

-d, --display=DISPLAY — Connect to DISPLAY (default: :0)
-h, --help — Show this help and exit
-V, --version — Show version info and exit
-p, --proc — This creates a ruby proc from the given argument and yields the result of the group to it as parameter param.

Examples:

subtler -cl -p "puts param.name"
subtler -cC -p "param.gravity = { terms: :left }"

💫 MODIFIER

-r, --reload — Reload subtle
-R, --restart — Restart subtle
-q, --quit — Quit subtle
-C, --current — Select current active window/view instead of passing it via argument.

Example: subtler -cCf

-X, --select — Select a window via pointer instead of passing it via argument.

Example: subtler -cXf

🎀 GROUPS

-c, --Client — Use client group
-g, --Gravity — Use gravity group
-e, --Screen — Use screen group
-s, --Sublet — Use sublet group
-t, --Tag — Use tag group
-y, --Tray — Use tray group
-v, --View — Use views group

🪟 ACTIONS FOR CLIENTS

-f, --find => PATTERN — Find client

Example: subtler -cf urxvt

-o, --focus => PATTERN — Set focus to client

Example: subtler -co urxvt

-F, --full => PATTERN — Toggle full

Example: subtler -cF urxvt

-O, --float => PATTERN — Toggle float

Example: subtler -cO urxvt

-S, --stick => PATTERN — Toggle stick

Example: subtler -cS urxvt

-N, --urgent => PATTERN — Toggle urgent

Example: subtler -cN urxvt

-l, --list — List all clients
-T, --tag => PATTERN — Add tag to client

Example: subtler -cT urxvt tag

-U, --untag => PATTERN NAME — Remove tag from client

Example: subtler -cU urxvt tag

-G, --tags => PATTERN — Show client tags

Example: subtler -cG urxvt

-Y, --gravity => PATTERN PATTERN — Set client gravity

Example: subtler -cY urxvt gravity

-E, --raise => PATTERN — Raise client window

Example: subtler -cE urxvt

-L, --lower => PATTERN — Lower client window

Example: subtler -cL urxvt

-k, --kill => PATTERN — Kill client

Example: subtler -ck urxvt

🧲 ACTIONS FOR GRAVITIES

-a, --add => NAME GEOMETRY — Create new gravity

Example: subtler -ga test 0x0+100+100

-l, --list — List all gravities

Example: subtler -gl

-f, --find => PATTERN — Find a gravity

Example: subtler -gf center

-k, --kill => PATTERN — Kill gravity

Example: subtler -gk center

🖥️ ACTIONS FOR SCREENS

-l, --list — List all screens

Example: subtler -el

-f, --find => ID — Find a screen

Example: subtler -ef 0

🧩 ACTIONS FOR SUBLETS

-l, --list — List all sublets

Example: subtler -sl

-f, --find => PATTERN — Find sublet

Example: subtler -sf sublet

-u, --update — Updates value of sublet

Example: subtler -su

-D, --data => PATTERN DATA — Send data to sublet

Example: subtler -sD sublet something

-k, --kill => PATTERN — Kill sublet

Example: subtler -sk PATTERN

🏷️ ACTIONS FOR TAGS

-a, --add => NAME — Create new tag

Example: subtler -ta tag

-f, --find => PATTERN — Find all clients/views by tag

Example: subtler -ta tag

-l, --list — List all tags

Example: subtler -tl

-I, --clients — Show clients with tag

Example: subtler -tI

-k, --kill => PATTERN — Kill tag

Example: subtler -tk PATTERN

🍓 ACTIONS FOR TRAYS

-f, --find => PATTERN — Find a tray

Example: subtler -yf PATTERN

-l, --list — List all trays

Example: subtler -yl

-k, --kill => PATTERN — Kill tray

Example: subtler -yk PATTERN

👑 ACTIONS FOR VIEWS

-a, --add => NAME — Create new view

Example: subtler -va NAME

-f, --find => PATTERN — Find a view

Example: subtler -vf PATTERN

-l, --list — List all views

Example: subtler -vl

-T, --tag => PATTERN NAME — Add tag to view

Example: subtler -vT terms tag

-U, --untag => PATTERN NAME — Remove tag from view