Console IRC client

Latest on Hackage:2.29

This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow to host generated Haddocks.

ISC licensed by Eric Mertens
Maintained by

GLIRC - Advanced Console IRC Client

  • glirc Hackage Build Status
  • irc-core Hackage
  • hookup Hackage

Wiki Documentation


glirc uses recent versions of packages, make sure you package databases are up-to-date:

$ cabal update

To install the latest version from Hackage using cabal-install:

$ cabal install glirc

Building with cabal-install from source checkout

$ cabal install --dep
$ cabal build

Client Features

  • All views and transformation are dynamic and don’t change the underlying model.
  • Subsequent joins and parts fold into one line and do not scroll chat messages off the screen
  • Ignore support that folds ignored messages into the joins and parts. Toggle it off to see previously hidden messages
  • Detailed view to see all the messages in a channel in full detail with hostmask and timestamp (F2)
  • Context sensitive tab completion
  • Searchable ban, quiet, invex, and exception view separate from chat messages
  • Searchable user list, detailed view shows full hostmasks
  • WYSIWYG mIRC formatting input
  • Multi-line editing
  • Dynamic, in-place message searching
  • Chanserv integration
  • Nicknames in chat messages are colored to match messages from that nickname
  • Support for /STATUSMSG/ messages (messages only voice or op users can see)
  • Run commands upon connection
  • Command macros
  • CERTFP and SASL authentication
  • Split-screen view
  • Configurable color palette


  -c PATH  --config=PATH  Configuration file path
  -!       --noconnect    Disable autoconnecting
  -h       --help         Show help
  -v       --version      Show version

Environment variables

USER=<default nickname and username>
IRCPASSWORD=<your irc password>

Configuration file

A configuration file can currently be used to provide some default values instead of using command line arguments. If any value is missing the default will be used.

The default configuration file path is ~/.config/glirc/config

Relative paths are relative to the home directory.

Learn more about this file format at config-value

-- vim: filetype=config-value
-- Grab the Vim syntax highlighting file from the config-value package

-- Learn more about these settings with `glirc2 --config-format`

-- Defaults used when not specified on command line
  nick:            "yournick"
  username:        "yourusername"
  realname:        "Your real name"
  password:        "IRC server password"
  tls:             yes -- or: yes-insecure or no
                       -- enabling tls automatically uses port 6697
  tls-client-cert: "/path/to/cert.pem"
  tls-client-key:  "/path/to/cert.key"

-- Override the defaults when connecting to specific servers
  * name: "fn"
    hostname:      ""
    sasl-username: "someuser"
    sasl-password: "somepass"
    socks-host:    ""
    socks-port:    8080 -- defaults to 1080
    log-dir:       "/home/myuser/ircLogs"

  * name: "example"
    hostname:      ""
    port:          7000 -- override the default port
      * "join #favoritechannel,#otherchannel"
      * "msg mybot another command"

    -- Specify additional certificates beyond the system CAs
    -- relative to home directory
    tls-server-cert: "extra/certificate.pem"

  * name: "wipe"
      * "clear"
      * "znc *status clearbuffer $channel"

  * name: "mysplits"
      * "splits fn:#haskell fn:#haskell-offtopic"

  -- Example use of macro in combination with an extension
  * name: "extra"
      * "extension Lua some-parameter $network $channel"

extra-highlights: ["glirc", "lens"]

   side: left -- try right if you don't like left padding
   width: 13

url-opener: "open" -- This works on macOS, "gnome-open" for GNOME

  * bind: "C-M-b"
    command: "masks b"

  line-marker: yellow
    fg: [10,10,10] -- RGB values for color for timestamps
    bg: blue
    [ cyan, magenta, green, yellow, blue
    , bright-cyan, bright-magenta, bright-green, bright-blue
    , 218,  88,  89, 124, 160, 205, 212, 224 -- reds
    ,  94, 130, 166, 172, 208, 214, 216, 180 -- oranges
    ,  58, 226, 229, 184, 187, 100, 142, 220 -- yellows
    ,  22,  34,  40,  82,  70,  64,  48,  85 -- greens
    ,  25,  27,  33,  39,  51,  80,  81,  75 -- blues
    ,  69,  61,  56,  54, 129,  93,  99, 147 -- purples

Configuration sections:

setting type description
defaults server These settings are used for all connections
servers list of servers These settings are used to override defaults when the hostname matches
palette palette Client color overrides
window-names text Names of windows (typically overridden on non QWERTY layouts)
nick-padding nonnegative integer Nicks are padded until they have the specified length
indent-wrapped-lines nonnegative integer How far to indent lines when they are wrapped
extra-highlights list of text Extra words/nicks to highlight
extensions list of text Filenames of extension to load
url-opener text Command to execute with URL parameter for /url e.g. gnome-open on GNOME or open on macOS
ignores list of text Initial list of nicknames to ignore
activity-bar yes or no Initial setting for visibility of activity bar (default no)
bell-on-mention yes or no Sound terminal bell on transition from not mentioned to mentioned (default no)
macros list of macros User-configurable client commands

Server Settings

setting type description
name text name of server entry, defaults to hostname
hostname text hostname used to connect and to specify the server
port number port number, defaults to 6667 without TLS and 6697 with TLS
nick text or list of text nicknames to try in order
username text server username
realname text real name / GECOS
password text server password
sasl-username text SASL username
sasl-password text SASL password (PLAIN mode)
sasl-ecdsa-key text Path ecdsa private key file (ECDSA-NIST256P-CHALLENGE mode)
tls yes/yes-insecure/no use TLS to connect (insecure mode disables certificate checks)
tls-client-cert text path to TLS client certificate
tls-client-key text path to TLS client key
tls-server-cert text CA certificate to use when validating certificates
tls-ciphers text OpenSSL cipher suite description string
connect-cmds list of text client commands to send upon connection
socks-host text hostname of SOCKS proxy to connect through
socks-port number port number of SOCKS proxy to connect through
chanserv-channels list of text list of channels with chanserv op permission
flood-penalty number cost in seconds per message
flood-threshold number threshold in seconds for burst
message-hooks list of text names of hooks to enable
reconnect-attempts int number of reconnections to attempt on error
autoconnect yes or no automatically connect at client startup
nick-completion default or slack set this to slack to use @ sigils when completing nicks


entry type description
nick-colors list of attr Use for nick highlights
self attr our own nickname(s) outside of mentions
self-highlight attr our own nickname(s) in mentions
time attr timestamp on messages
meta attr metadata (joins/parts/etc.)
sigil attr sigils (+@)
label attr information labels
latency attr latency time
error attr error messages
textbox attr textbox edges (^$)
window-name attr current window name
activity attr activity notification
mention attr mention notification
command attr recognized command
command-prefix attr prefix of known command
command-ready attr recognized command with arguments filled
command-placeholder attr command argument placeholder
window-divider attr the dividing line between split windows
line-marker attr the dividing line for new messages

Text Attributes

Text attributes can be specified either as a single foreground color or section of attributes.

  • <number> - Maps to a terminal color
  • <name> - Direct selection of standard 16 terminal colors
  • [red-number, blue-number, green-number] - List of 3 numbers in range 0-255 map to an approximation of the RGB color.


  • fg - foreground color
  • bg - background color
  • style - single style or list of styles


  • blink
  • bold
  • dim
  • standout
  • reverse-video
  • underline


Client commands

  • /help [command] - Show in-client help
  • /exit - Terminate the client
  • /quit - Gracefully terminate connection to the current server
  • /connect <name> - Connect to the given server
  • /disconnect - Forcefully terminate connection to the current server
  • /reconnect - Reconnect to the current server
  • /reload [path] - Load a new configuration file (optional path)
  • /palette - Show the client palette
  • /digraphs - Show the table of digraphs
  • /mentions - Show all the highlighted lines across all windows
  • /extension <extension name> <params...> - Send the given params to the named extension
  • /exec [-n network] [-c channel] <command> <arguments...> - Execute a command, If no network or channel are provided send output to client window, if network and channel are provided send output as messages, if network is provided send output as raw IRC messages.
  • /url [n] - Execute url-opener on the nth URL in the current window (defaults to first)

View toggles

  • /toggle-detail - toggle full detail view of messages
  • /toggle-activity-bar - toggle channel names in activity bar
  • /toggle-metadata - toggle visibility of channel metadata
  • /toggle-layout - toggle split-screen layout between 1 and 2 column view

Connection commands

  • /nick <nick> - Change nickname
  • /away <message> - Set away status

Window management

  • /windows [filter] - List all open windows (filters: networks, channels, users)
  • /focus <server> - Change focus to server window
  • /focus <server> <channel> - Change focus to channel window
  • /clear [network] [channel] - Clear contents of current or specified window
  • /ignore - Show all ignore masks
  • /ignore <mask>... - Toggle ignore status on a list of masks
  • /channel <channel> - Change focus to channel on current network (alias: /c)
  • /splits [focuses...] - Enable split-screen view. Focuses should be space delimited list of NETWORK:CHANNEL
  • /splits+ [focuses...] - Incremental addition to splits
  • /splits- [focuses...] - Incremental removal from splits

Channel membership

  • /join <channel> - Join a channel (alias: /j)
  • /part - Part from current channel

Chat commands

  • /query <target> [<msg>] - Switch focus to target window on current server, optionally send message
  • /msg <target> <msg> - Send a message on the current server to target
  • /notice <target> <msg> - Send a notice message on the current server to target
  • /ctcp <target> <command> <args> - Send a ctcp command on the current server to target
  • /me <msg> - Send action message to channel
  • /say <msg> - Send normal message to channel

Channel management

  • /mode <mode> <params> - Change modes on the current channel (advanced tab completion)
  • /kick <nick> - Kick a user
  • /kickban <nick> - Kick and ban a user
  • /remove - Gracefully kick a user
  • /topic <topic> - Change the topic (tab completion for topic)
  • /invite <nick> - Invite a user to the current channel


  • /who <query> - Perform WHO query (use detailed view to see output)
  • /whois <nick> - Perform WHOIS query
  • /whowas <nick> - Perform WHOWAS query
  • /ison <nick> - Perform ISON query
  • /userhost <nick> - Perform USERHOST query
  • /links <server> - Perform LINKS query
  • /time - Perform TIME query
  • /stats <query> - Perform STATS query

Channel information

  • /users - Show channel user list
  • /masks <mode> - Show channel bans(b), quiets(q), exempts(e), or invex(I)
  • /channelinfo - Show channel topic, creation, url

Window filters

  • /grep - Filter chat messages using a regular expression
  • /grepi - Filter chat messages using a case-insensitive regular expression on the message


  • /znc <module> <parameters> - send command to ZNC module without echoing to all clients
  • /znc-playback - ZNC playback module - play everything
  • /znc-playback <time> - ZNC playback module - play everything start at the given time today
  • /znc-playback <date> <time> - ZNC playback module - play everything start at the given time


  • /quote <raw command> - Send a raw IRC command to the server

Keyboard Shortcuts

Note that these keybindings are using Emacs syntax. C-a means “hold control and press A”. M-a means “hold meta key and press A”. On most modern keyboards the Meta key is labeled Alt or Option.

Window navigation

  • C-n next window
  • C-p previous window
  • C-x next network
  • M-# jump to window - 1234567890qwertyuiop!@#$%^&*()QWERTYUIOP
  • M-a jump to activity
  • M-s jump to previous window
  • ESC return to messages view (from userlist, masklist, help, etc)


  • C-a beginning of line

  • C-e end of line

  • C-k delete to end

  • C-u delete to beginning

  • C-d delete at cursor

  • C-w delete word backwards

  • C-y paste from yank buffer

  • C-t swap characters at cursor

  • M-f forward word

  • M-b backward word

  • M-Right forward word

  • M-Left backward word

  • M-Backspace delete word backwards

  • M-d delete word forwards

  • M-Enter insert newline

  • M-k insert digraph (2-characters before cursor)

  • Tab nickname completion

Client settings

  • F2 toggle detailed view
  • F3 toggle detailed activity bar
  • F4 toggle metadata visibility


  • Page Up scroll up
  • Page Down scroll down


  • C-b bold
  • C-c color
  • C-v reverse video
  • C-_ underline
  • C-] italic
  • C-o reset formatting


The macros configuration section allows you to define sequences of commands. These commands can contain expansions.


  • name - text - name of macro
  • arguments - text - space separated list of argument names (suffix name with ? when optional)
  • commands - list of text - commands to send after expansion

Macro Expansions

Variable names and integer indexes can be used when defining commands. Variables are specified with a leading $. For disambiguation a variable name can be surrounded by {}. $channel and ${channel} are equivalent. Default values can be provided following a pipe: ${var|default}.

  • channel - current channel
  • network - current network name
  • nick - current nickname

The arguments to a command will be mapped to integer indexes. The command itself is at index zero.

  • 0 - command
  • 1 - first argument
  • 2 - second argument (etc.)



Enable this hook when using ZNC and the buffextra module in order to reinterpret this module’s messages natively in the client.


Revision history for glirc2


  • Add support for timers to the extension API
  • Add glirc_set_focus API call


  • Add formatting reference to /palette
  • Make RTLD flags configurable when loading an extension
  • Update client’s internal hostname on RPL_HOSTHIDDEN
  • Support IRCv3.2 server-time extension over ZNC-specific one
  • Lots of work on the Lua extension code and documentation
  • Added glirc_user_account and glirc_user_channel_modes extension API entrypoints.
  • Added support for account-notify and extended-join
  • Added configurable “arguments” to the C extensions


  • Requires GHC 8.4
  • Show channel topic in channel on join
  • Fix socket leak when failing to load TLS certificates
  • Add delay when indicating sent ping to reduce noise
  • Add support for italics in formatting


  • Updates for GHC 8.4.1
  • Added /toggle-show-ping and show-ping configuration setting to toggle visibility of the ping round-trip times.


  • /ignore can list ignores and supports full wildcard masks
  • Updated C extension API
  • Improved OTR extension to avoid interacting with ZNC replays
  • Added protocol-family configuration option. Set to inet or inet6 to force a particular IP protocol.


  • /query now takes a message parameter and tab-completes like /msg.


  • CONFIGURATION FILE CHANGE: Relative paths are now resolved from the directory of the configuration file. The “~” alias for the home directory works for resolving paths relative to $HOME. Absolute paths are unmodified.

  • Support network:#channel in /query

  • Add an optional OTR extension. See the otr-extension/ directory and the wiki for more information.

  • Extended the C API with glirc_inject_chat and chat_entrypoint

  • Smarter WYSIWYG highlighting in text edit box. Nicknames are highlighted and /mode command parameters get correct placeholders.

  • Added more information to /palette

  • Added “human readable” labels to /rtsstats


  • Added dynamic indentation of wrapped lines. Lines now wrap to where the message portion of the line started. This removes indent-wrapped-lines configuration setting
  • Added pervasive word-boundary oriented line wrapping (beyond what was previously restricted to chat messages)
  • Made nick prefix padding configurable to be on left or right. See nick-padding setting in glirc2 --config-format. In addition this setting is now reconfigurable at runtime via /reload
  • Added /oper command for network operator authentication.
  • Memory savings by packing message timestamp information, and using the “detailed” image for regular expression matching.
  • Added /rtsstats command for inspecting the GHC RTS statistics
  • Added many minor IRC query commands: admin, info, map, rules motd, version, lusers, kill, knock, list.


  • Support for latest config-schema
  • Adapt extension API to help support stub Rust extension


  • Make metadata toggle F4 a window-level setting instead of client level
  • Add configuration option to hide metadata by default hide-metadata
  • Make keymap configurable under key-bindings, add /keymap command
  • Add transient error message view, press ESC to clear
  • Implement two-column split window mode: /toggle-layout and F5
  • Implement word-boundary based line wrapping


  • Switch to new config-schema package for configuration file loading.
  • Add --config-format flag to executable to show configuration file format.


  • Add line indicating message since previous time window was focused. The palette for this is configurable as line-marker


  • Add /query alias for /channel
  • Add /names alias for /users
  • Update to build on GHC 8.2.1-rc1 with Cabal-


  • Nicer /help system, commands are grouped
  • Added /splits+ and /splits- for incremental updates to splits
  • Jump-to-activity returns to original window after activity is visited
  • Extended activity view makes use of empty space above text input
  • Parse the timestamp and duration from /whois response

  • Support vty-5.15


  • Remove memory dependency
  • Add indent-wrapped-lines setting

  • Remove macro dependency on happy and alex being installed for version information


  • Support vty-5.11.1


  • Move from tls to HsOpenSSL support via the new hookup package


  • Smarter text box tracks “scroll” position independently from cursor
  • Added --full-version flag
  • Remove regex-tdfa-text dependency
  • Added bell-on-mention client setting
  • Added ExportCApi cabal flag to help with loading the client in GHCi


  • Add digraph support under M-k and /digraphs
  • Add ECDSA-NIST256P-CHALLENGE support for Freenode via Tor
  • Load mask list on /masks
  • Add C-x to change to next network window
  • Allow /clear NETWORK * to clear all windows for the given network


  • Add reconnect-attempts setting
  • Add persistence for /grep and /grepi
  • Add filter argument to /windows
  • Better tab completion for /channel and /focus
  • Isolate and number URLs in view with /url
  • Map M-Left and M-Right to backward word and forward word


  • Add /splits to show multiple chat windows simultaneously


  • Add /mentions
  • Add macro argument declarations
  • Add indication when a command is still a prefix or not of a valid command
  • Support quoted strings arguments to /exec
  • Add F4 to toggle visibility of metadata lines
  • tls-insecure setting was incorrectly behaving like normal insecure
  • Add C-t to swap characters
  • Add ESC to return to messages window


  • Add /help
  • Add /palette
  • Add F3 to toggle activity detail bar


  • Add disconnect expansion, support expansions in connect-cmds
  • Add default expansion syntax ${var|default}
  • Add support for multiple nicknames to try on connect
  • Add ignores section to configuration
  • Add url-opener section to configuration and /url command


  • Remove tls-insecure configuration option in favor of tls: yes-insecure
  • Implement fancy command placeholder rendering and argument parsing
  • Improved reconnect logic
  • Improved connection error messages


  • Add M-S to jump to previously focused window
  • Add extra-highlights section
  • Tab complete server names in /connect
  • Add /windows command for listing active windows
  • Add glirc_clear_window C API procedure
  • Allow process_message callback to drop messages
  • Add optional network and channel arguments to /clear (intended to assist macros)
  • Automatically reconnect on ping timeout
  • Many commands will report message to client window on error


  • Fixes for multi-line editing
  • Multiple, sequential kills all fill the same yank buffer


  • Dynamically loadable extensions
  • Implement Lua scripting extension
  • Enable support for batch messages
  • Grow metadata lines to the right


  • Support vty-5.8
  • Implement initial support for macros
  • Support


  • Switch to regex-tdfa (easier to install on MacOS than text-icu)
  • Tab-complete starts with most recent nick
  • Add /reload
  • Add custom palette entry for self highlights
  • Add ability to set background colors and styles in palette


  • connect-cmds now use actual client commands instead of raw IRC messages. For example msg user my message or join #mychannel
  • Multiple lines can be held in the textbox at once. Pasting multiple lines insert those lines into the textbox rather than sending them immediately.
  • Added M-d and M-Enter key bindings
  • Added name field to server configuration
  • Extract irc-core library again
  • Configurable self color


  • Add facilities for hooks that can alter the IRC message stream.
  • Implement a hook that handles the ZNC buffextras plugin.
  • Implement configurable nick color highlight palette.
  • Resolve relative paths starting at the home directory.
  • Significantly configurable UI colors


  • Support XDG configuration directory, e.g. ~/.config/glirc/config
  • Add more window names. Shift selects second set of names.
  • Add /channel and /say
  • Improve /focus tab completion


  • Add commands /znc
  • Add initial support for ZNC’s playback module and /znc-playback command
  • Don’t consider message seen when in masklist, userlist, or channelinfo windows
  • Add terminal bell on command error


  • Add commands /ison, /userhost, /away, /notice, /ctcp, /links, /time, /stats
  • Added context-sensitive completion to /mode
  • Render CTCP messages
  • Memory performance improvements
  • Improved logic on nick changes
  • Support for fractional flood settings
  • Fixed VTY formatting bug
  • Add counts to the mask and user lists


  • Add red highlighting for own nick
  • Synchronize reply codes with Freenode
  • Add textual interpretation of reply codes
  • Add SASL support
  • Add /channelinfo command


  • First version of glirc rewrite
comments powered byDisqus