2.1 Sample Session

This example ERC session describes how to connect to the ‘#emacs’ channel on Libera.Chat. Also worth checking out is Libera’s own introductory guide to IRC, https://libera.chat/guides/basics, which presents a more comprehensive overview without instructions specific to ERC.

• Connect to Libera.Chat

  Run M-x erc RET. Use ‘irc.libera.chat’ for the server and ‘6667’ for the port. Choose a nickname, and hit y when asked if you’d prefer to connect over TLS.

• Get used to the interface

  Switch to the Libera.Chat buffer if you’re not already there. ERC calls this a server buffer, and it must exist for the duration of the session. You will likely see some messages about “ident”, authentication, and the like, followed by information describing the current server and the network.

• Join the #emacs channel

  In the server buffer, type /join #emacs RET at the prompt. ERC will create a new buffer called #emacs. If you’ve already configured ERC, you may need to switch to it manually. Once there, you will see the channel’s “topic” in the buffer’s header line (see (elisp)Header Lines) and a list of people currently in the channel. If you can’t see the full topic, mouse over it or type /topic RET at the prompt.

• Register your nickname with Libera.Chat

  In order to access essential network features, like speaking in certain channels and participating in private conversations, you’ll likely have to “register” your nickname. To do so, switch to the Libera.Chat buffer and type /msg NickServ register ‘<password>’ ‘<email>’ RET, replacing ‘<password>’ and ‘<email>’ with your desired account password and contact email (both sans quotes). The server should tell you that the operation was successful. See the official Libera.Chat docs if you encounter problems.

  In addition to creating an account, this process also “authenticates” you to the network’s “account services” system for the duration of the session. In other words, you’re now logged in. However, when you connect in the future, you’ll need to authenticate again by providing the same credentials somehow. When you’re finished with this walk through, see “Next Steps”, below, to learn some ways to do that.

• Talk to people in the channel

  Switch back to the #emacs buffer and type a message at the prompt, hitting RET once satisfied. Everyone in the channel will now see your message.

• Open a query buffer to talk to someone

  If you want to talk with someone in private, type /query ‘<nick>’ RET, replacing ‘<nick>’ with the their nickname. As before, with the server buffer, if this new query buffer doesn’t appear in the current window, you may have to switch to it. Regardless, its name should match ‘<nick>’. Once there, type something at the prompt and hit RET, and the other party will see it.

  Keep in mind that if either party isn’t authenticated, you may not be able to converse at all. Also, depending on the network, certain social conventions may apply to the practice of direct messaging. As a general rule, queries should usually be reserved for personal matters rather than technical help, which can often benefit (and benefit from) a larger audience.

• Next steps

  Try joining another channel, such as ‘#erc’, where ERC users and developers hang out (see Official IRC channels for more on the history of ‘#emacs’). For ideas on various options to customize, see Sample Configuration. To learn how ERC can authenticate you to the network automatically whenever you connect, see Authenticating via SASL. As always, if you encounter problems, see Getting Help and Reporting Bugs.

2.2 Special Features

ERC has some features that distinguish it from some IRC clients.

• multiple channels and multiple servers

  Every channel is put in a separate buffer. Several IRC servers may be connected to at the same time.

• private message separation

  Private conversations are treated as channels, and are put into separate buffers in Emacs. We call these “query buffers”.

• highlighting

  Some occurrences of words can be highlighted, which makes it easier to track different kinds of conversations.

• notification

  ERC can notify you that certain users are online.

• channel tracking

  Channels can be hidden and conversation continue in the background. You are notified when something is said in such a channel that is not currently visible. This makes it easy to get Real Work done while still maintaining an IRC presence.

• nick completion

  ERC can complete words upon hitting TAB, which eases the writing of nicknames in messages.

• history

  Past actions are kept in history rings for future use. To navigate a history ring, hit M-p to go backwards and M-n to go forwards.

• multiple languages

  Different channels and servers may have different language encodings.

  multiple languages. Please contact the Emacs developers if you are interested in helping with the translation effort.

• user scripting

  Users can load scripts (e.g., auto greeting scripts) when ERC starts up.

  It is also possible to make custom IRC commands, if you know a little Emacs Lisp. Just make an Emacs Lisp function and call it erc-cmd-NEWCOMMAND, where NEWCOMMAND is the name of the new command in capital letters.

• auto reconnect

  If the connection goes away at some point, ERC will try to reconnect automatically. If it fails to reconnect, and you want to try to manually reestablish the connection at some later point, switch to an ERC buffer and run the /RECONNECT command.

5.1 Connecting to an IRC Server

The easiest way to connect to an IRC server is to call M-x erc. If you want to assign this function to a keystroke, the following will help you figure out its parameters.

Function: erc ¶

Select connection parameters and run ERC. Non-interactively, it takes the following keyword arguments.

• server
• port
• nick
• user
• password
• full-name
• id

For example, calling the command like so

(erc :server "irc.libera.chat" :full-name "J. Random Hacker")

sets server and full-name directly while leaving the rest up to functions like erc-compute-port. Note that some arguments can’t be specified interactively. id, in particular, is rarely needed (see Network Identifier).

To connect securely over an encrypted TLS connection, use M-x erc-tls.

Function: erc-tls ¶

Select connection parameters and run ERC over TLS. Non-interactively, it takes the following keyword arguments.

• server
• port
• nick
• user
• password
• full-name
• id
• client-certificate

That is, if called in the following manner

(erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker")

the command will set server and full-name accordingly, while helpers, like erc-compute-nick, will determine other parameters, and some, like client-certificate, will just be nil.

To use a certificate with erc-tls, specify the optional client-certificate keyword argument, whose value should be as described in the documentation of open-network-stream: if non-nil, it should either be a list where the first element is the file name of the private key corresponding to a client certificate and the second element is the file name of the client certificate itself to use when connecting over TLS, or t, which means that auth-source will be queried for the private key and the certificate. Authenticating using a TLS client certificate is also referred to as “CertFP” (Certificate Fingerprint) authentication by various IRC networks.

Examples of use:

(erc-tls :server "irc.libera.chat" :port 6697
         :client-certificate
         '("/home/bandali/my-cert.key"
           "/home/bandali/my-cert.crt"))

(erc-tls :server "irc.libera.chat" :port 6697
         :client-certificate
         `(,(expand-file-name "~/cert-libera.key")
           ,(expand-file-name "~/cert-libera.crt")))

(erc-tls :server "irc.libera.chat" :port 6697
         :client-certificate t)

In the case of :client-certificate t, you will need to add a line like the following to your authinfo file (e.g. ~/.authinfo.gpg):

machine irc.libera.chat key /home/bandali/my-cert.key cert /home/bandali/my-cert.crt

See Help for users in Emacs auth-source Library, for more on the .authinfo/.netrc backend of auth-source. For other uses of auth-source throughout ERC, see ERC’s auth-source integration.

Server

Function: erc-compute-server &optional server ¶

Return an IRC server name.

This tries a number of increasingly more default methods until a non-nil value is found.

• server (the argument passed to this function)
• The erc-server option
• The value of the IRCSERVER environment variable
• The erc-default-server variable

User Option: erc-server ¶

IRC server to use if one is not provided.

Port

Function: erc-compute-port &optional port ¶

Return a port for an IRC server.

This tries a number of increasingly more default methods until a non-nil value is found.

• port (the argument passed to this function)
• The erc-port option
• The erc-default-port variable

User Option: erc-port ¶

IRC port to use if not specified.

This can be either a string or a number.

Nick

Function: erc-compute-nick &optional nick ¶

Return user’s IRC nick.

This tries a number of increasingly more default methods until a non-nil value is found.

• nick (the argument passed to this function)
• The erc-nick option
• The value of the IRCNICK environment variable
• The result from the user-login-name function

User Option: erc-nick ¶

Nickname to use if one is not provided.

This can be either a string, or a list of strings. In the latter case, if the first nick in the list is already in use, other nicks are tried in the list order.

User Option: erc-show-speaker-membership-status ¶

A boolean for including a channel member’s status prefix in their display name when they speak.

User Option: erc-nick-uniquifier ¶

The string to append to the nick if it is already in use.

User Option: erc-try-new-nick-p ¶

If the nickname you chose isn’t available, and this option is non-nil, ERC should automatically attempt to connect with another nickname.

You can manually set another nickname with the /NICK command.

User

Function: erc-compute-user &optional user ¶

Determine a suitable value to send as the first argument of the opening ‘USER’ IRC command by consulting the following sources:

• user, the argument passed to this function
• The option erc-email-userid, assuming erc-anonymous-login is non-nil
• The result of calling the function user-login-name

User Option: erc-email-userid ¶

A permanent username value to send for all connections. It should be a string abiding by the rules of the network.

Password

This parameter was traditionally meant to specify a server password to be sent along with the IRC ‘PASS’ command. However, such passwords aren’t widely used. Instead, networks typically expect them, when present, to convey other authentication information. In the case of account-services (a.k.a., “NickServ”) credentials, this typically involves a special syntax, such as ‘myuser:mypass’. IRC bouncers often do something similar but include a pre-configured network-ID component, for example, ‘bncuser/mynet:bncpass’.

In general, if you have not been asked by your network or bouncer to specify a repurposed server password, you should instead consider setting up ‘services’ or, preferably, ‘sasl’, both ERC modules (see Modules). In addition to performing network-account authentication, these obviate the need for this parameter completely, although both can optionally borrow it for their own purposes. (See SASL in ERC.)

User Option: erc-prompt-for-password ¶

If non-nil (the default), M-x erc and M-x erc-tls prompt for a server password. This only affects interactive invocations of erc and erc-tls.

If you prefer, you can set this option to nil and use the auth-source facility to retrieve a server password, although hitting RET at the prompt may achieve the same effect. See ERC’s auth-source integration, for more.

Full name

Function: erc-compute-full-name &optional full-name ¶

Return user’s full name.

This tries a number of increasingly more default methods until a non-nil value is found.

• full-name (the argument passed to this function)
• The erc-user-full-name option
• The value of the IRCNAME environment variable
• The result from the user-full-name function

User Option: erc-user-full-name ¶

User full name.

This can be either a string or a function to call.

ID

ERC uses an abstract designation, called network context identifier, for referring to a connection internally. While normally derived from a combination of logical and physical connection parameters, an ID can also be explicitly provided via an entry-point command (like erc-tls). Use this in rare situations where ERC would otherwise have trouble discerning between connections.

One such situation might arise when using multiple connections to the same network with the same nick but different (nonstandard) ‘device’ identifiers, which some bouncers may support. Another might be when mimicking the experience offered by popular standalone clients, which normally offer “named” persistent configurations with server buffers reflecting those names. Yet another use case might involve third-party code needing to identify a connection unequivocally, but in a human-friendly way suitable for UI components.

When providing an ID as an entry-point argument, strings and symbols make the most sense, but any reasonably printable object is acceptable.

5.2 Authenticating via SASL

If you’ve used SASL elsewhere, you can probably skip to the examples below. Otherwise, if you haven’t already registered with your network, please do so now, referring to the network’s own instructions for details. If you’re new to IRC and using a bouncer, know that you probably won’t be needing this for the client-to-bouncer connection.

When you’re ready to get started, add sasl to erc-modules, like you would any other module. If unsure which mechanism to choose, stick with the default of ‘PLAIN’. Then try C-u M-x erc-tls RET, and give your account name for the ‘user’ parameter and your account password for the ‘server password’.

User Option: erc-sasl-mechanism ¶

The name of an SASL subprotocol type as a lowercase symbol. The value can be one of the following:

plain or scram (“password-based”)

Here, “password” refers to your account password, which is usually your ‘NickServ’ password. To make this work, customize erc-sasl-user and erc-sasl-password or specify the :user and :password keyword arguments when invoking erc-tls.

external (via client TLS certificate)

This works in conjunction with the :client-certificate keyword offered by erc-tls. Just ensure you’ve registered your fingerprint with the network beforehand. The fingerprint is usually a SHA1 or SHA256 digest in either "normalized" or "openssl" forms. The first is lowercase without delims (‘deadbeef’) and the second uppercase with colon seps (‘DE:AD:BE:EF’). These days, there’s usually a ‘CERT ADD’ command offered by NickServ that can register you automatically if you issue it while connected with a client cert. See client-certificate.

Additional considerations:

1. Most IRCds will allow you to authenticate with a client cert but without the hassle of SASL (meaning you may not need this module).
2. Technically, EXTERNAL merely indicates that an out-of-band mode of authentication is in effect (being deferred to), so depending on the specific application or service, there’s a remote chance your server has something else in mind.

ecdsa-nist256p-challenge

This mechanism is quite complicated and currently requires the external ‘openssl’ executable, so please use something else if at all possible. Ignoring that, specify your key file (e.g., ‘~/pki/mykey.pem’) as the value of erc-sasl-password, and then configure your network settings. On servers running Atheme services, you can add your public key with ‘NickServ’ like so:

ERC> /msg NickServ set property \
     pubkey AgGZmlYTUjJlea/BVz7yrjJ6gysiAPaQxzeUzTH4hd5j

(You may be able to omit the ‘property’ subcommand.)

User Option: erc-sasl-user ¶

This should be your network account username, typically the same one registered with nickname services. Specify this when your NickServ login differs from the :user you’re connecting with. See username parameter.

User Option: erc-sasl-password ¶

As noted elsewhere, the entry-point :password param was originally intended for traditional “server passwords,” but these aren’t really used any more (see password parameter). As such, this option defaults to borrowing that parameter for its own uses, thus allowing you to call erc-tls with :password set to your NickServ password.

You can also set this to a nonemtpy string, and ERC will send that when needed, no questions asked. Or, if you’d rather use auth-source, set erc-sasl-auth-source-function to a function, and ERC will perform an auth-source query instead. In all cases, ERC will prompt you for input as a last resort.

Lastly, if your mechanism is ecdsa-nist256p-challenge, this option should instead hold the file name of your key.

User Option: erc-sasl-auth-source-function ¶

This is nearly identical to the other ERC ‘auth-source’ function options (see auth-source functions) except that the default value here is nil, meaning you have to set it to something like erc-auth-source-search for queries to be performed. For convenience, this module provides the following as a possible value:

Function: erc-sasl-auth-source-password-as-host &rest plist ¶

Setting erc-sasl-auth-source-function to this function tells ERC to use erc-sasl-password for the :host field when querying auth-source, even if its value is the default :password, in which case ERC knows to “resolve” it to erc-session-password and use that as long as it’s non-nil. Otherwise, ERC just defers to erc-auth-source-search to determine the :host, along with everything else.

As long as this option specifies a function, ERC will pass it the “resolved” value of erc-sasl-user for the auth-source :user param.

User Option: erc-sasl-authzid ¶

In the rarest of circumstances, a network may want you to specify a specific role or assume an alternate identity. In most cases, this happens because the server is buggy or misconfigured. If you suspect such a thing, please contact your network operator. Otherwise, just leave this set to nil.

Examples

• Defaults

  (erc-tls :server "irc.libera.chat" :port 6697
           :nick "aph"
           :user "APHacker"
           :password "changeme")
  

  Here, after adding sasl to erc-modules via the Customize interface, you authenticate to Libera.Chat using the ‘PLAIN’ mechanism and your NickServ credentials, ‘APHacker’ and ‘changeme’.

• External

  (setopt erc-sasl-mechanism 'external)
  
  (erc-tls :server "irc.libera.chat" :port 6697 :nick "aph"
           :client-certificate
           '("/home/aph/my.key" "/home/aph/my.crt"))
  

  You decide to switch things up and try out the ‘EXTERNAL’ mechanism. You follow your network’s instructions for telling NickServ about your client-certificate’s fingerprint, and you authenticate successfully.

• Multiple networks

  # ~/.authinfo.gpg
  
  machine irc.libera.chat key /home/aph/my.key cert /home/aph/my.crt
  machine Example.Net login alyssa password sEcReT
  machine Example.Net login aph-bot password sesame
  

  ;; init.el
  
  (defun my-erc-up (network)
    (interactive "Snetwork: ")
    (require 'erc-sasl)
    (or (let ((erc-modules (cons 'sasl erc-modules)))
          (pcase network
            ('libera
             (let ((erc-sasl-mechanism 'external))
               (erc-tls :server "irc.libera.chat"
                        :client-certificate t)))
            ('example
             (let ((erc-sasl-auth-source-function
                    #'erc-sasl-auth-source-password-as-host))
               (erc-tls :server "irc.example.net"
                        :user "alyssa"
                        :password "Example.Net")))))
        ;; Non-SASL
        (call-interactively #'erc-tls)))
  

  You’ve started storing your credentials with auth-source and have decided to try SASL on another network as well. But there’s a catch: this network doesn’t support ‘EXTERNAL’. You use let-binding to work around this and successfully authenticate to both networks. (Note that this example assumes you’ve removed sasl from erc-modules globally and have instead opted to add it locally when connecting to preconfigured networks.)

Troubleshooting

First and foremost, please know that ERC’s SASL offering is currently limited by a lack of support for proper IRCv3 capability negotiation. In most cases, this shouldn’t affect your ability to authenticate.

If you’re struggling, remember that your SASL password is almost always your NickServ password. When in doubt, try restoring all SASL options to their defaults and calling erc-tls with :user set to your NickServ account name and :password to your NickServ password. If you’re still having trouble, please contact us (see Getting Help and Reporting Bugs).

As you try out different settings, keep in mind that it’s best to create a fresh session for every change, for example, by calling erc-tls from scratch. More experienced users may be able to get away with cycling erc-sasl-mode and issuing a ‘/reconnect’, but that’s generally not recommended. Whatever the case, you’ll probably want to temporarily disable erc-server-auto-reconnect while experimenting.

5.3 Sample Configuration

Here is an example configuration for ERC. Don’t panic if you aren’t familiar with ‘use-package’ or have no interest in learning it. For our purposes, it’s just a means of presenting configuration details in a tidy, standardized format. If it helps, just pretend it’s some make-believe, pseudo configuration language. And while the syntax below is easy enough to intuit and adapt to your setup, you may wish to keep the following in mind:

• Each use-package “declaration” focuses on a library “feature”, which is just a symbol you’d normally require in your config.
• Emacs loads anything in a :config section after loading whatever library provides the declaration’s feature.
• Everything in a :custom or :custom-face section is basically something you’d find in your custom-file.
• For more info, see (elisp)Named Features, or see (use-package)Top.

The following would typically go in your init file. Experienced users may opt to keep any non-settings, like commands and functions, in a dedicated ~/.emacs.d/.ercrc.el. Whatever the case, please keep in mind that you can replace nearly all of the following with Custom settings (see Sample configuration via Customize).

;;; My ERC configuration -*- lexical-binding: t -*-

(use-package erc
  :config
  ;; Prefer SASL to NickServ, colorize nicknames, and show side panels
  ;; with joined channels and members
  (setopt erc-modules
          (seq-union '(sasl nicks bufbar nickbar scrolltobottom)
                     erc-modules))

  :custom
  ;; Protect me from accidentally sending excess lines.
  (erc-inhibit-multiline-input t)
  (erc-send-whitespace-lines t)
  (erc-ask-about-multiline-input t)
  ;; Scroll all windows to prompt when submitting input.
  (erc-scrolltobottom-all t)

  ;; Reconnect automatically using a fancy strategy.
  (erc-server-reconnect-function #'erc-server-delayed-check-reconnect)
  (erc-server-reconnect-timeout 30)

  ;; Show new buffers in the current window instead of a split.
  (erc-interactive-display 'buffer)

  ;; Insert a newline when I hit <RET> at the prompt, and prefer
  ;; something more deliberate for actually sending messages.
  :bind (:map erc-mode-map
              ("RET" . nil)
              ("C-c C-c" . #'erc-send-current-line))

  ;; Emphasize buttonized text in notices.
  :custom-face (erc-notice-face ((t (:slant italic :weight unspecified)))))

(use-package erc-sasl
  ;; Since my account name is the same as my nick, free me from having
  ;; to hit C-u before M-x erc to trigger a username prompt.
  :custom (erc-sasl-user :nick))

(use-package erc-join
  ;; Join #emacs and #erc whenever I connect to Libera.Chat.
  :custom (erc-autojoin-channels-alist '((Libera.Chat "#emacs" "#erc"))))

(use-package erc-fill
  :custom
  ;; Prefer one message per line without continuation indicators.
  (erc-fill-function #'erc-fill-wrap)
  (erc-fill-static-center 18)

  :bind (:map erc-fill-wrap-mode-map ("C-c =" . #'erc-fill-wrap-nudge)))

(use-package erc-track
  ;; Prevent JOINs and PARTs from lighting up the mode-line.
  :config (setopt erc-track-faces-priority-list
                  (remq 'erc-notice-face erc-track-faces-priority-list))

  :custom (erc-track-priority-faces-only 'all))

(use-package erc-goodies
  ;; Turn on read indicators when joining channels.
  :hook (erc-join . my-erc-enable-keep-place-indicator-on-join))

(defvar my-erc-read-indicator-channels '("#emacs")
  "Channels in which to show a `keep-place-indicator'.")

(defun my-erc-enable-keep-place-indicator-on-join ()
  "Enable read indicators for certain queries or channels."
  (when (member (erc-default-target) my-erc-read-indicator-channels)
    (erc-keep-place-indicator-mode +1)))

;; Handy commands from the Emacs Wiki.
(defun erc-cmd-TRACK (&optional target)
  "Start tracking TARGET or that of current buffer."
  (setq erc-track-exclude
        (delete (or target (erc-default-target) (current-buffer))
                erc-track-exclude)))

(defun erc-cmd-UNTRACK (&optional target)
  "Stop tracking TARGET or that of current buffer."
  (setq erc-track-exclude
        (cl-pushnew (or target (erc-default-target) (current-buffer))
                    erc-track-exclude
                    :test #'equal)))

Those familiar with use-package may have noticed the lack of :defer keyword args. This was done to conserve space, but you can just pretend that this user has enabled use-package-always-defer elsewhere.

Via Customize

As mentioned, Customize users can accomplish nearly all of the above via the Customize interface. Start by running M-x customize-group RET erc RET, and search for “Modules” with C-s modules RET. Toggle open the flyout menu to reveal the full widget panel, a web-form-like interface for “Erc Modules”. Tick the boxes for ‘bufbar’, ‘nickbar’, ‘nicks’, ‘sasl’, and ‘scrolltobottom’.

Next, search for the phrases “Erc Ask About Multiline Input”, “Erc Inhibit Multiline Input”, and “Erc Send Whitespace Lines”. These are the print names of three boolean options that control how ERC treats prompt input containing line breaks. When visiting each option’s section, twirl open its triangle icon to reveal its widget UI, and click its ‘[Toggle]’ button to set its value to t. While going about this, you may find it helpful to glance at the descriptions just in case you want to disable them later. When finished, hit C-x C-s or click ‘[Apply and Save]’ atop the buffer.

Now do the same for another couple options, this time having to do with automatic reconnection. But instead of searching for their print names, try running M-x customize-option RET ‘<option>’ RET, replacing ‘<option>’ with:

• erc-server-reconnect-function, a function
• erc-server-reconnect-timeout, a number

(If it helps, hit TAB for completion.) As you may have noticed, when customizing options individually, each buffer displays but a single option’s widget. When you get to the buffer for “Erc Server Reconnect Function”, you’ll see that ‘[Toggle]’ has been replaced with ‘[Value Menu]’ and that clicking it reveals three choices in a pop-up window. Enter 1 to select erc-server-delayed-check-reconnect before TAB’ing over to ‘[State]’ and hitting RET. Enter 1 again, this time to persists your changes.

For the final option, erc-server-reconnect-timeout, you’ll encounter a text field (instead of a button), which works like those in a typical web form. Enter ‘30’ and hit C-x C-s to save. Just for fun, click the group link for ‘Erc Server’ at the bottom of the buffer. You could just as well have set the last two options from this “custom group” buffer alone, which very much resembles the one for the ‘Erc’ group, which is actually the “parent” of this group (note the “breadcrumb” for group ‘Erc’ atop the buffer). Indeed, you can always get back here by running M-x customize-group RET erc-server RET from almost anywhere in Emacs.

To make sure you’ve got this, try quickly customizing the option erc-interactive-display, which lives in the ‘Erc Buffers’ group (M-x customize-group RET erc-buffers RET). As its doc string explains, the option controls where new buffers show up when you do M-x erc-tls RET or issue certain slash commands, like /JOIN #emacs-beginners RET, at ERC’s prompt. Change its value to the symbol buffer by choosing ‘Use current window’ (item 5) from the option’s ‘[Value Menu]’. Don’t forget to save.

If you need more practice, try enabling the boolean option erc-scrolltobottom-all, which lives in the ‘Erc Display’ group (M-x customize-group RET erc-display RET). When enabled, this option tells the ‘scrolltobottom’ module to adjust all ERC windows instead of just the one you’re currently typing in.

Now it’s time to set some key bindings for erc-mode-map, a major-mode keymap active in all ERC buffers. In general, it’s best to do this part either entirely or in conjunction with some lisp code in you init file. However, to keep things “simple”, we’ll do it all in customization buffers. To get started, hit M-x customize-group RET erc-hooks RET and search for “Erc Mode Hook”. In the widget form, click ‘[INS]’, and paste the following into the value field in place of the default text.

(lambda ()
  (keymap-set erc-mode-map "RET" nil)
  (keymap-set erc-mode-map "C-c C-c" 'erc-send-current-line))

Don’t worry about the line breaks. Emacs is smart enough to handle those. When you’re ready, click ‘[Apply and Save]’.

Next, try tweaking the face ERC uses to stylize server messages that say things like “SoAndSo has joined channel #chan”. Type M-x customize-face RET erc-notice-face RET. Click the “link”-looking button at the very bottom that says something like “Show All Attributes”. Untick ‘Weight’ and tick ‘Slant’. Then, in the latter’s ‘[Value Menu]’, enter ‘0’ for ‘italic’. Hit C-x C-s to save.

Time for some more involved configuring. From now on, if something isn’t applicable to your setup, just skip ahead. Also, note that if you’ve installed ERC from GNU ELPA, you may need to load libraries for groups and options you’d like to customize before Emacs can create a customization buffer. For example, to do this for the group erc-sasl, run M-: (require 'erc-sasl) RET.

Speaking of SASL, those already authenticating with it may have noticed that connecting interactively requires running C-u M-x erc-tls RET in order to receive a “User” prompt for your account name. However, if your nickname happens to be the same as your account name, you can avoid the leading C-u by customizing the option erc-sasl-user to the keyword symbol :nick. At the time of writing, you’d hit 2 when prompted by the option’s ‘[Value menu]’. Hit C-x C-s to save your changes.

One of ERC’s most configured options lives in erc-join, and it determines the channels you join upon connecting. To make it work for you, customize the option erc-autojoin-channels-alist. In the customization widget, hit ‘[INS]’ to create a new entry. In the ‘Network:’ field, type ‘Libera.Chat’. Under ‘Channels:’, hit ‘[INS]’ again, this time to create a field to enter a channel name, and enter ‘#emacs’. Now, find and click on the lowermost ‘[INS]’, and this time enter ‘#erc’ in the ‘Name:’ field. Save your changes.

If you’re new to ERC, you may not be familiar with the various ways it can “fill” message text by inserting line breaks. The most modern fill style is called fill-wrap, and it’s available by customizing erc-fill-function to erc-fill-wrap, which appears as ‘Dynamic word-wrap’ in the option’s ‘[Value Menu]’. After setting this, change the related option erc-fill-static-center to the integer ‘18’. Save your changes. As a bonus exercise, try binding the key C-c = to the function erc-fill-wrap-nudge in the minor-mode keymap erc-fill-wrap-mode-map (hint: the minor mode’s hook is called erc-fill-wrap-mode-hook, and it’s not a member of any customization group).

ERC users tend to be picky about the mode line. If you find that you’d rather not see changes when people join and leave channels, customize the option erc-track-faces-priority-list. When visiting its customization buffer, you’ll notice it’s quite busy. Ignore everything and type C-s erc-notice-face RET. Click the ‘[DEL]’ button at the beginning of the line you end up on, and save your changes. Next, customize the related option erc-track-priority-faces-only to the ‘[Value Menu]’ choice ‘all’. Once again, save your changes.

Let’s say you’d like to enable a local module (ERC’s version of a local minor mode) in a specific channel. One way to do that is by running some code to activate the module if the channel’s name matches. Try that now by customizing the option erc-join-hook. Add the following in the value field before saving your changes:

(lambda ()
  (require 'erc-goodies)
  (when (equal (erc-default-target) "#emacs")
    (erc-keep-place-indicator-mode +1)))

Lastly, if you really want the two slash commands defined at the end of the previous section, you can put them in any file listed in erc-startup-file-list, such as ~/.emacs.d/.ercrc.el. Make sure to put (require 'erc-track) near the top of the file. These will allow you to type /TRACK RET and /UNTRACK RET in channels and query buffers to tell ERC whether to show activity from these buffers in the mode line.

5.4 Integrations

• URL
• SOCKS
• auth-source
• display-buffer

  '("\\birc6?s?://[][a-z0-9.,@_:+%?&/#-]+" 0 t browse-url-irc 0)

curl --proxy socks5h://localhost:9050 https://check.torproject.org | \
  grep 'Congratulations'

(require 'erc)
(require 'socks)

(defun my-erc-open-socks-tls-stream (&rest args)
  (let ((socks-username "")
        (socks-password "")
        (socks-server '("tor" "localhost" 9050 5)))
    (apply #'erc-open-socks-tls-stream args)))

(let* ((erc-modules (cons 'sasl erc-modules))
       (erc-sasl-mechanism 'external)
       (erc-server-connect-function #'my-erc-open-socks-tls-stream))
  (erc-tls
   :server "libera75jm6of4wxpxt4aynol3xjmbtxgfyjpu34ss4d7r7q2v5zrpyd.onion"
   :port 6697
   :nick "jrh"
   :user "jrandomhacker"
   :full-name "J. Random Hacker"
   :client-certificate (list "/home/jrh/key.pem" "/home/jrh/cert.pem")))

machine irc.example.net login mynick password sEcReT

machine Libera/cellphone login MyNick password sEcReT
machine Libera.Chat login MyNick password sEcReT
machine zirconium.libera.chat login MyNick password sEcReT
machine irc.libera.chat login MyNick password sEcReT

(defun my-fancy-auth-source-func (&rest _)
  (let* ((host (read-string "host: " nil nil "default"))
         (pass (auth-source-pick-first-password :host host)))
    (if (and pass (string-search "libera" host))
        (concat "MyNick:" pass)
      pass)))

(defun my-erc-interactive-display-buffer (buffer action)
  "Pop to BUFFER when running \\[erc-tls], clicking a link, etc."
  (when-let ((alist (cdr action))
             (found (alist-get 'erc-interactive-display alist)))
    (if (eq found 'erc-tls)
        (pop-to-buffer-same-window buffer action)
      (pop-to-buffer buffer action))))

(setopt erc-interactive-display #'my-erc-interactive-display-buffer)

(defun my-erc-disp-entry-p (_ action)
  (memq (cdr (or (assq 'erc-buffer-display action)
                 (assq 'erc-interactive-display action)))
        '(erc-tls url)))

(defun my-erc-disp-query-p (_ action)
  (or (eq (cdr (assq 'erc-interactive-display action)) '/QUERY)
      (and (eq (cdr (assq 'erc-receive-query-display action)) 'PRIVMSG)
           (member (erc-default-target) '("bob" "alice")))))

(defun my-erc-disp-chan-p (_ action)
  (or (assq 'erc-autojoin-mode action)
      (and (eq (cdr (assq 'erc-buffer-display action)) 'JOIN)
           (member (erc-default-target) '("#emacs" "#fsf")))))

(setopt erc-buffer-display #'display-buffer
        erc-interactive-display #'display-buffer
        erc-receive-query-display #'display-buffer
        ;;
        erc-auto-reconnect-display 'bury)

(setopt display-buffer-alist

        ;; Create new frame with M-x erc-tls RET or (erc-tls ...)
        '(((and (major-mode . erc-mode) my-erc-disp-entry-p)
           display-buffer-pop-up-frame
           (reusable-frames . visible))

          ;; Show important chans and queries in a split.
          ((and (major-mode . erc-mode)
                (or my-erc-disp-chan-p my-erc-disp-query-p))
           display-buffer-pop-up-window)

          ;; Ignore everything else.
          ((major-mode . erc-mode)
           display-buffer-no-window
           (allow-no-window . t))))

5.5 Options

This section is extremely incomplete. For now, the easiest way to check out all the available options for ERC is to do M-x customize-group RET erc RET.

User Option: erc-hide-list ¶

If non, nil, this is a list of IRC message types to hide, e.g.:

(setq erc-hide-list '("JOIN" "PART" "QUIT"))

User Option: erc-network-hide-list ¶

If non, nil, this is a list of IRC networks and message types to hide, e.g.:

(setq erc-network-hide-list (("Libera.Chat" "JOIN" "PART" "QUIT")
("OFTC" "JOIN" "PART""))

User Option: erc-channel-hide-list ¶

If non, nil, this is a list of IRC channels and message types to hide, e.g.:

(setq erc-channel-hide-list (("#erc" "JOIN" "PART" "QUIT")
("#emacs" "NICK"))

User Option: erc-lurker-hide-list ¶

Like erc-hide-list, but only applies to messages sent by lurkers. The function erc-lurker-p determines whether a given nickname is considered a lurker.