Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
HERBSTCLIENT(1) 						 HERBSTCLIENT(1)

NAME
     herbstclient - sends commands to a running herbstluftwm instance via X

SYNOPSIS
     herbstclient [OPTIONS] COMMAND [ARGS ...]

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

DESCRIPTION
     Sends  a  COMMAND	with  its  (optional)  arguments ARGS to a running herb-
     stluftwm(1) instance via Xlib. If COMMAND has an output, it is  printed  by
     herbstclient.  If	output	does  not  end with a newline, then a newline is
     added to improve readability.

     See herbstluftwm(1) for a list of available COMMANDs and their ARGS.

     If --wait or --idle is passed, then it waits for hooks  from  herbstluftwm.
     The hook is printed, if it matches the optional FILTER. FILTERs are regular
     expressions. For a list of available hooks see herbstluftwm(1).

OPTIONS
     -n, --no-newline
	 Do not print a newline if output does not end with a newline.

     -0, --print0
	 Use the null character as delimiter between the output of hooks.

     -l, --last-arg
	 When using -i or -w, only print the last argument of the hook.

     -i, --idle
	 Wait for hooks instead of executing commands.

     -w, --wait
	 Same as --idle but exit after first --count hooks.

     -c, --count COUNT
	 Let  --wait  exit  after COUNT hooks were received and printed. The de-
	 fault COUNT is 1.

     -q, --quiet
	 Do not print error messages if herbstclient cannot connect to the  run-
	 ning herbstluftwm instance.

     -v, --version
	 Print	the  herbstclient  version. To get the herbstluftwm version, use
	 herbstclient version.

     -h, --help
	 Print the herbstclient usage with its command line options.

     --binary-pipe
	 Run multiple commands via a binary interface. The protocol is described
	 in the BINARY PIPE section below.

BINARY PIPE
     When --binary-pipe is passed,  a  binary  communication  channel  to  herb-
     stluftwm  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 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 for-
	 get to flush!

     On  stdout,  null-byte  separated key-value pairs are printed, that is, the
     output will always be a sequence of the format KEY 0 VALUE 0. The	protocol
     may  be extended in the future, but will always stick to the key-value-for-
     mat.

     *	 STDOUT 0 TEXT 0 means that the stdout of the recently executed  command
	 is TEXT

     *	 STDERR  0 TEXT 0 means that the stderr of the recently executed command
	 is TEXT

     *	 STATUS 0 N 0 means that the exit status of the recently  executed  com-
	 mand is the integer N

     Whenever  herbstluftwm  quits or when the EOF of stdin is reached, then the
     binary pipe also closes and herbstclient exits.

     Example:

	 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, i.e. where herbstluftwm(1) is running.

EXIT STATUS
     Returns the exit status of the COMMAND execution in herbstluftwm(1) server.

     0
	 Success.

     other
	 Failure. See herbstluftwm(1) for a list of error codes.

BUGS
     See the herbstluftwm Github  issues:  https://github.com/herbstluftwm/herb-
     stluftwm/issues

COMMUNITY
     Feel free to join the IRC channel #herbstluftwm on irc.libera.chat.

AUTHOR
     herbstclient  was	written by Thorsten WiAmann. All contributors are listed
     in the herbstluftwm distribution AUTHORS file.

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 WiAmann. All rights reserved.

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

  herbstluftwm 0.9.6		   2026-04-03			 HERBSTCLIENT(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=herbstclient&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help