polybar-msg

Quit the bar

$ polybar-msg cmd quit

$ polybar-msg cmd restart

$ polybar-msg cmd hide

$ polybar-msg cmd show

$ polybar-msg cmd toggle

$ polybar-msg action "#[module_name].[action_name].[data_string]"

$ polybar-msg -p [pid] [cmd|action] [payload]

polybar-msg [OPTIONS] MESSAGE_TYPE [ARGUMENTS...]

Common Message Types:
• polybar-msg command <command_name>
• polybar-msg module <module_name> <action>
• polybar-msg hook <module_name> <hook_id>
• polybar-msg reload
• polybar-msg restart
• polybar-msg quit

-p <PID>, --pid <PID>
    Specifies the Process ID (PID) of the Polybar instance to which the message should be sent. If omitted, the message is sent to all running Polybar instances.

-c <PATH>, --socket <PATH>
    Directly specifies the IPC socket path to use for communication. Useful if the default socket location is changed or multiple sockets exist.

-s <PATH>, --socket-dir <PATH>
    Specifies the directory where Polybar's IPC sockets are located. Defaults to `/tmp/polybar/`.

-H, --no-prefix
    Suppresses the `[polybar-msg]` prefix from the output messages.

-h, --help
    Displays a concise help message explaining the command's usage and available options.

-v, --version
    Prints the version information of the polybar-msg utility.

<MESSAGE_TYPE>
    The type of message or action to send. This can be command, module, hook, reload, restart, quit, list-commands, help, or version.

<ARGUMENTS...>
    Additional arguments required by certain MESSAGE_TYPEs, such as <command_name> for command messages, or <module_name> <action> for module messages.

polybar-msg is a utility designed to communicate with running Polybar instances using Inter-Process Communication (IPC). It allows users and scripts to send various commands and actions to Polybar bars, enabling dynamic control without restarting the bar. This is particularly useful for integrating Polybar with other scripts, keybindings, or system events. Common uses include reloading bar configurations, toggling module visibility, executing internal Polybar commands, and triggering module hooks. By default, polybar-msg attempts to send messages to all active Polybar processes. However, it provides options to target a specific bar using its Process ID (PID) or by directly specifying the IPC socket path. This command acts as a crucial interface for automating and extending Polybar's functionality.

polybar-msg requires that Polybar is running and has IPC enabled in its configuration (which is usually the default for recent versions).

If no specific PID or socket path is provided, the message will be sent to all currently running Polybar instances, which might not always be the desired behavior in multi-bar setups.

The exact syntax and available commands/modules/hooks depend on the specific Polybar version and the user's configuration. Use polybar-msg list-commands for a current list of available internal commands.

• command <command_name>: Executes an internal Polybar command, such as hide, show, toggle, fullscreen, monitor, etc.
Example: polybar-msg command toggle

• module <module_name> <action>: Sends a specific action to a named module. Common actions include toggle, set-icon, open, close, etc., depending on the module type.
Example: polybar-msg module i3 toggle

• hook <module_name> <hook_id>: Triggers a custom hook for a custom/script or custom/ipc module. This allows external scripts to update module content.
Example: polybar-msg hook my_script_module 1

• reload / restart / quit: Control the entire Polybar instance, reloading its configuration, restarting the bar, or gracefully quitting it.

polybar-msg was developed as an integral part of the Polybar project to provide a standardized Inter-Process Communication (IPC) interface. This allowed for more robust and flexible control of Polybar instances from external scripts or user input, improving its extensibility and integration capabilities within a desktop environment. Its development has mirrored Polybar's evolution, with new message types and functionalities added to support new features in the bar itself.

polybar(1), i3(1), bspwm(1)