i3-nagbar

Display an error

$ i3-nagbar [[-m|--message]] "[error message]"

$ i3-nagbar [[-t|--type]] warning [[-m|--message]] "[warning message]"

$ i3-nagbar [[-f|--font]] "[pango:monospace bold 9]" [[-m|--message]] "[error message]"

$ i3-nagbar [[-b|--button]] "[button text]" [command] [[-m|--message]] "[error message]"

$ i3-nagbar [[-B|--button-no-terminal]] "[button text]" [command] [[-m|--message]] "[error message]"

$ i3-nagbar [[-pm|--primary --message]] "[error message]"

i3-nagbar [-v|--version] [-h|--help]
                [-t type|--type type]
                [-m message|--message message]
                [-f font|--font font]
                [-b label:command|--button label:command] ...

-v, --version
    Displays the i3-nagbar version and exits.

-h, --help
    Displays a short help message and exits.

-t type, --type type
    Specifies the type of message. Valid types are error, warning, and message. This influences the default colors used, which are defined in the i3 configuration file.

-m message, --message message
    The text message to be displayed in the nagbar.

-f font, --font font
    Specifies the font to be used for the message and buttons. For example, 'pango:monospace 8'.

-b label:command, --button label:command
    Adds a button to the nagbar. When the button is clicked, the specified command is executed. Multiple -b options can be used to add several buttons. The command can be any shell command.

i3-nagbar is a dedicated utility for the i3 window manager, designed to display persistent and often critical messages to the user. Unlike transient notifications, the nagbar appears as a bar at the top of the screen and typically remains visible, sometimes blocking further interaction with i3 until dismissed or an action is taken. It serves as an essential channel for system-level communication, commonly invoked for error reporting, critical warnings, or to solicit user confirmation for significant actions, such as restarting i3 or exiting the session. The utility supports displaying custom text messages and allows for the inclusion of multiple interactive buttons. Each button can be configured to execute a specific shell command upon being clicked, enabling direct user interaction within the notification context. Its appearance can be subtly customized through type-based color schemes (error, warning, message) that defer to the main i3 configuration for consistent theming. This makes i3-nagbar an indispensable tool for ensuring users are aware of and can respond to important events within their i3 environment.

Older color-related command-line options are deprecated; i3-nagbar now relies on the i3 configuration file for its visual theming. The utility requires the i3 window manager to be running and an X display environment to function correctly. Due to its persistent and sometimes modal nature, it can temporarily block user interaction with the i3 desktop until a resolution is provided or the bar is explicitly dismissed via a button action.

While i3-nagbar does not offer direct command-line color options anymore, its appearance is highly customizable through the i3 configuration file. The `client.urgent`, `client.focused_inactive`, and `client.unfocused` directives, among others, influence the nagbar's colors based on the -t type option used. This integration ensures a consistent look and feel with your overall i3 theme.

i3-nagbar is frequently used in scripts or directly by i3 for critical interactions. Examples include asking for confirmation before exiting i3 (`i3-nagbar -m "Quit i3?" -b "Yes:i3-msg exit" -b "No:exit 0"`), reporting configuration file errors (`i3-nagbar -t error -m "Configuration error: line 123" -b "Edit:$EDITOR ~/.config/i3/config"`), or displaying system-level warnings that require immediate attention.

i3-nagbar has been an integral part of the i3 window manager project since its early development. It was conceived to provide a direct and unavoidable mechanism for i3 to communicate critical information or solicit user decisions. Over time, its development has seen refinements, particularly concerning its aesthetic customization, where direct command-line color options were deprecated in favor of leveraging the unified theming definitions within the main i3 configuration file. This evolution reflects a broader effort to centralize and simplify configuration management within the i3 ecosystem, ensuring consistency across all i3 components.

i3(1), i3-msg(1), i3-config(5)