HERBSTCLIENT(1)

📦
version 0.9.6 · 6 versions
, in arch rolling

💅 HERBSTCLIENT — the group chat bridge to your window manager

okay so real quick, before we get into it: this is the manual page for herbstclient, a program that slides into your herbstluftwm(1) instance's DMs via X and delivers your commands. bestie behavior, honestly. 🫶

✨ SYNOPSIS ✨

herbstclient [OPTIONS] COMMAND [ARGS ...]
herbstclient [OPTIONS] [--wait|--idle] [FILTER ...]

🌸 DESCRIPTION 🌸

So here's the vibe: herbstclient sends a COMMAND (plus its optional arguments ARGS) over to a running herbstluftwm(1) instance through Xlib. That's the whole gig. 💌

If your COMMAND has output, herbstclient prints it for you. And here's a tiny detail that is so considerate: if that output doesn't end with a newline, a newline gets added anyway — purely for readability. she said "i'm not letting your terminal look a mess." 💅

Need the list of available COMMANDs and their ARGS? That's in herbstluftwm(1), babes. go look. 📖

Now — if you pass --wait or --idle, herbstclient stops running commands and just waits for hooks from herbstluftwm. The hook gets printed only if it matches the optional FILTER. Heads up: FILTERs are regular expressions, so mind your syntax. For the full menu of available hooks, again, see herbstluftwm(1). ✨

🎀 OPTIONS 🎀

  • -n, --no-newline — the anti-nicety flag. Do not print a newline if the output doesn't already end with one.
  • -0, --print0 — uses the null character as the delimiter between hook outputs. for the binary girlies 🦋
  • -l, --last-arg — when you're using -i or -w, only print the last argument of the hook. just the finale, no opening act.
  • -i, --idle — wait for hooks instead of executing commands. eternal hydration break.
  • -w, --wait — same as --idle, except it dips out after the first --count hooks. lowkey the introvert version of --idle.
  • -c, --count COUNT — makes --wait exit after COUNT hooks have been received and printed. default COUNT is 1. one and done unless you say otherwise.
  • -q, --quiet — don't print error messages when herbstclient can't connect to the running herbstluftwm instance. silence is golden, denial is free 🙈
  • -v, --version — prints the herbstclient version. and yes, this trips everyone up: to get the herbstluftwm version, you run herbstclient version. two different things, bestie, don't mix them.
  • -h, --help — prints the herbstclient usage along with its command line options.
  • --binary-pipe — runs multiple commands through a binary interface. the full protocol lives in the BINARY PIPE section right below 👇

🧚 BINARY PIPE 🧚

Okay this is the fancy one. When you pass --binary-pipe, a binary communication channel gets established to herbstluftwm so you can run multiple commands through a single herbstclient instance. efficiency! 💅

Both stdin and stdout are in binary mode, while the stderr channel stays in text mode. The interface is made of null-byte terminated UTF-8 text tokens.

These are the token sequences supported on stdin, where 0 denotes a null-byte:

  • ARG 0 T 0 — pushes the text token T to the next command to be run.
  • RUN 0 — runs the command, i.e. sends it to herbstluftwm.
  • After writing RUN and the nullbyte to herbstclient's stdin, do not forget to flush! 🔥 this is the part that will get you, fr fr.

On stdout, null-byte separated key-value pairs are printed — so the output is always a sequence of the format KEY 0 VALUE 0. The protocol may get extended in the future, but it will always stick to that key-value format. promise. 🫶

  • STDOUT 0 TEXT 0 — means the stdout of the recently executed command is TEXT
  • STDERR 0 TEXT 0 — means the stderr of the recently executed command is TEXT
  • STATUS 0 N 0 — means the exit status of the recently executed command is the integer N

Whenever herbstluftwm quits, or when the EOF of stdin is reached, the binary pipe closes too and herbstclient exits. it's a whole "if you leave, i leave" situation 😭

Example — look at it, it's iconic:

printf 'ARG\0echo\0ARG\0hello world\0RUN\0ARG\0get_attr\0ARG\0tags.count\0RUN\0' \
    | herbstclient --binary-pipe \
    | hexdump -C

🌈 ENVIRONMENT VARIABLES 🌈

  • DISPLAY — specifies the DISPLAY to use, meaning where herbstluftwm(1) is running. basically, tell her where the party's at. 🎉

⭐ EXIT STATUS ⭐

Returns the exit status of the COMMAND execution in the herbstluftwm(1) server. so whatever the server says, that's what you get.

  • 0 — Success. slay. 👑
  • other — Failure. See herbstluftwm(1) for a list of error codes. it's giving "go read the other doc." 💀

💀 BUGS 💀

See the herbstluftwm Github issues:

https://github.com/herbstluftwm/herbstluftwm/issues

🦋 COMMUNITY 🦋

Feel free to join the IRC channel #herbstluftwm on irc.libera.chat. come hang out, we don't bite 🫶

💜 AUTHOR 💜

herbstclient was written by Thorsten Wißmann. All contributors are listed in the herbstluftwm distribution AUTHORS file. legends, all of them.

📚 RESOURCES 📚

Homepage: http://herbstluftwm.org

Github page: http://github.com/herbstluftwm/herbstluftwm

Patch submission and bug reporting:

hlwm@lists.herbstluftwm.org

🍓 COPYING 🍓

Copyright 2011-2020 Thorsten Wißmann. All rights reserved.

This software is licensed under the "Simplified BSD License". See LICENSE for details.

k that's the whole page, bestie 💖 this was herbstluftwm version 0.9.6, dated 2026-04-03, and yes the manual section is still HERBSTCLIENT(1) — go forth and boss your window manager around ✨🎀

📦 where this page comes from