'\" t
.\"     Title: herbstclient
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2026-04-03
.\"    Manual: \ \&
.\"    Source: \ \& herbstluftwm 0.9.6
.\"  Language: English
.\"
.TH "HERBSTCLIENT" "1" "2026\-04\-03" "\ \& herbstluftwm 0\&.9\&.6" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
herbstclient \- sends commands to a running herbstluftwm instance via X
.SH "SYNOPSIS"
.sp
\fBherbstclient\fR [\fIOPTIONS\fR] \fICOMMAND\fR [\fIARGS \&...\fR]
.sp
\fBherbstclient\fR [\fIOPTIONS\fR] [\fI\-\-wait\fR|\fI\-\-idle\fR] [\fIFILTER \&...\fR]
.SH "DESCRIPTION"
.sp
Sends a \fICOMMAND\fR with its (optional) arguments \fIARGS\fR to a running \fBherbstluftwm\fR(1) instance via Xlib\&. If \fICOMMAND\fR has an output, it is printed by \fBherbstclient\fR\&. If output does not end with a newline, then a newline is added to improve readability\&.
.sp
See \fBherbstluftwm\fR(1) for a list of available \fICOMMAND\fRs and their \fIARGS\fR\&.
.sp
If \fI\-\-wait\fR or \fI\-\-idle\fR is passed, then it waits for hooks from \fBherbstluftwm\fR\&. The hook is printed, if it matches the optional \fIFILTER\fR\&. \fIFILTER\fRs are regular expressions\&. For a list of available hooks see \fBherbstluftwm\fR(1)\&.
.SH "OPTIONS"
.PP
\fB\-n\fR, \fB\-\-no\-newline\fR
.RS 4
Do not print a newline if output does not end with a newline\&.
.RE
.PP
\fB\-0\fR, \fB\-\-print0\fR
.RS 4
Use the null character as delimiter between the output of hooks\&.
.RE
.PP
\fB\-l\fR, \fB\-\-last\-arg\fR
.RS 4
When using
\fB\-i\fR
or
\fB\-w\fR, only print the last argument of the hook\&.
.RE
.PP
\fB\-i\fR, \fB\-\-idle\fR
.RS 4
Wait for hooks instead of executing commands\&.
.RE
.PP
\fB\-w\fR, \fB\-\-wait\fR
.RS 4
Same as
\fB\-\-idle\fR
but exit after first
\fB\-\-count\fR
hooks\&.
.RE
.PP
\fB\-c\fR, \fB\-\-count\fR \fICOUNT\fR
.RS 4
Let
\fB\-\-wait\fR
exit after
\fICOUNT\fR
hooks were received and printed\&. The default
\fICOUNT\fR
is 1\&.
.RE
.PP
\fB\-q\fR, \fB\-\-quiet\fR
.RS 4
Do not print error messages if herbstclient cannot connect to the running herbstluftwm instance\&.
.RE
.PP
\fB\-v\fR, \fB\-\-version\fR
.RS 4
Print the herbstclient version\&. To get the herbstluftwm version, use
\fBherbstclient version\fR\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print the herbstclient usage with its command line options\&.
.RE
.PP
\fB\-\-binary\-pipe\fR
.RS 4
Run multiple commands via a binary interface\&. The protocol is described in the
\fBBINARY PIPE\fR
section below\&.
.RE
.SH "BINARY PIPE"
.sp
When \fB\-\-binary\-pipe\fR is passed, a binary communication channel to herbstluftwm is established such that multiple commands can be run through a single herbstclient instance\&. Both stdin and stdout are in binary mode, whereas the stderr channel remains text mode\&. The interface consists of null\-byte terminated UTF\-8 text tokens\&. The following token sequences are supported on stdin, where \fB0\fR denotes a null\-byte:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBARG\fR
\fB0\fR
\fIT\fR
\fB0\fR
pushes the text token
\fIT\fR
to the next command to be run\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBRUN\fR
\fB0\fR
runs the command (i\&.e\&. sends it to herbstluftwm)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
After writing
\fIRUN\fR
and the nullbyte to herbstclient\(cqs stdin, do not forget to flush!
.RE
.sp
On stdout, null\-byte separated key\-value pairs are printed, that is, the output will always be a sequence of the format \fIKEY\fR \fB0\fR \fIVALUE\fR \fB0\fR\&. The protocol may be extended in the future, but will always stick to the key\-value\-format\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBSTDOUT\fR
\fB0\fR
\fITEXT\fR
\fB0\fR
means that the stdout of the recently executed command is
\fITEXT\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBSTDERR\fR
\fB0\fR
\fITEXT\fR
\fB0\fR
means that the stderr of the recently executed command is
\fITEXT\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBSTATUS\fR
\fB0\fR
\fIN\fR
\fB0\fR
means that the exit status of the recently executed command is the integer
\fIN\fR
.RE
.sp
Whenever herbstluftwm quits or when the EOF of stdin is reached, then the binary pipe also closes and herbstclient exits\&.
.sp
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
printf \*(AqARG\e0echo\e0ARG\e0hello world\e0RUN\e0ARG\e0get_attr\e0ARG\e0tags\&.count\e0RUN\e0\*(Aq \e
    | herbstclient \-\-binary\-pipe \e
    | hexdump \-C
.fi
.if n \{\
.RE
.\}
.SH "ENVIRONMENT VARIABLES"
.PP
DISPLAY
.RS 4
Specifies the
\fIDISPLAY\fR
to use, i\&.e\&. where
\fBherbstluftwm\fR(1) is running\&.
.RE
.SH "EXIT STATUS"
.sp
Returns the exit status of the \fICOMMAND\fR execution in \fBherbstluftwm\fR(1) server\&.
.PP
\fB0\fR
.RS 4
Success\&.
.RE
.PP
other
.RS 4
Failure\&. See
\fBherbstluftwm\fR(1)
for a list of error codes\&.
.RE
.SH "BUGS"
.sp
See the \fBherbstluftwm\fR Github issues: https://github\&.com/herbstluftwm/herbstluftwm/issues
.SH "COMMUNITY"
.sp
Feel free to join the IRC channel \fI#herbstluftwm\fR on \fIirc\&.libera\&.chat\fR\&.
.SH "AUTHOR"
.sp
\fBherbstclient\fR was written by Thorsten Wißmann\&. All contributors are listed in the \fBherbstluftwm\fR distribution AUTHORS file\&.
.SH "RESOURCES"
.sp
Homepage: http://herbstluftwm\&.org
.sp
Github page: http://github\&.com/herbstluftwm/herbstluftwm
.sp
Patch submission and bug reporting:
.sp
.if n \{\
.RS 4
.\}
.nf
hlwm@lists\&.herbstluftwm\&.org
.fi
.if n \{\
.RE
.\}
.SH "COPYING"
.sp
Copyright 2011\-2020 Thorsten Wißmann\&. All rights reserved\&.
.sp
This software is licensed under the "Simplified BSD License"\&. See LICENSE for details\&.