### User Mode Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Examples showing how to modify user modes using the MODE command.

```irc
:MODE WiZ -w
```

```irc
:Angel MODE Angel +i
```

```irc
MODE WiZ -o
```

--------------------------------

### Topic Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Examples for changing and viewing channel topics using the TOPIC command.

```irc
:Wiz TOPIC #test :New topic
```

```irc
TOPIC #test :another topic
```

```irc
TOPIC #test
```

--------------------------------

### Channel Mode Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Examples demonstrating the use of the MODE command to set various channel flags and parameters.

```irc
MODE #Finnish +im
```

```irc
MODE #Finnish +o Kilroy
```

```irc
MODE #Finnish +v Wiz
```

```irc
MODE #Fins -s
```

```irc
MODE #42 +k oulu
```

```irc
MODE #eu-opers +l 10
```

```irc
MODE &oulu +b
```

```irc
MODE &oulu +b *!*@*
```

```irc
MODE &oulu +b *!*@*.edu
```

--------------------------------

### Install irc3 using pip

Source: https://github.com/gawel/irc3/blob/main/docs/index.md

Standard installation command for the irc3 library.

```default
$ pip install irc3
```

--------------------------------

### SUMMON command examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Examples of using the SUMMON command to request a user from a server. The first example summons a user from the client's current server, while the second specifies a target server.

```irc
SUMMON jto                      ; summon user jto on the server's
                                   host
```

```irc
SUMMON jto tolsun.oulu.fi       ; summon user jto on the host which a
                                   server named "tolsun.oulu.fi" is
                                   running.
```

--------------------------------

### Run irc3 Help Command

Source: https://github.com/gawel/irc3/blob/main/CONTRIBUTING.rst

After installing irc3, run this command to display the help message and confirm the installation.

```bash
$ irc3 -h
```

--------------------------------

### Names Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Examples for listing visible users on specified channels or all channels using the NAMES command.

```irc
NAMES #twilight_zone,#42
```

```irc
NAMES
```

--------------------------------

### Install irc3 using pip

Source: https://github.com/gawel/irc3/blob/main/CONTRIBUTING.rst

Install the irc3 project locally using pip. This is useful for testing installation or development versions.

```bash
$ pip install .
```

--------------------------------

### Example bot configuration file

Source: https://github.com/gawel/irc3/blob/main/docs/index.md

This is an example of the config.ini file generated for a new bot. It includes settings for nick, server connection, SSL, SASL, autojoins, and plugin includes.

```ini
[bot]
nick = mybot
username = mybot

host = localhost
port = 6667

# uncomment this if you want ssl support
# ssl = true
# uncomment this if you don't want to check the certificate
# ssl_verify = CERT_NONE

# uncomment this if you want to use sasl authentication
# sasl_username = mybot
# sasl_password = yourpassword

includes =
    irc3.plugins.command
#    irc3.plugins.uptime
#    irc3.plugins.ctcp
    mybot_plugin

# the bot will join #mybot_channel
# ${#} is replaced by the # char
autojoins =
    ${#}mybot_channel

# Autojoin delay, disabled by default
# float or int value
# autojoin_delay = 3.1

# The maximum amount of lines irc3 sends at once.
# Default to 4, set to 0 to disable
# flood_burst = 10

# The number of lines per $flood_rate_delay seconds irc3 sends after reaching
# the $flood_burst limit.
# Default to 1
# flood_rate = 2

# The bot will send $flood_rate messages per $flood_rate_delay seconds
# Default to 1
# flood_rate_delay = 5

[irc3.plugins.command]
# command plugin configuration

# set command char
cmd = !

# set guard policy
guard = irc3.plugins.command.mask_based_policy

[irc3.plugins.command.masks]
# this section is used by the guard to secure the bot's command
# change your nickname and uncomment the line below
# mynick!*@* = all_permissions
* = view

```

--------------------------------

### RESTART Command Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

An example of the RESTART command, used by an operator to restart the server. This command is optional and processed only by the connected server.

```irc
RESTART                         ; no parameters required.
```

--------------------------------

### JOIN Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Demonstrates various ways to use the JOIN command to enter channels, with and without keys, and to leave all channels.

```irc
JOIN #foo,&bar fubar
                                   ; Command to join channel #foo using
                                   key "fubar" and &bar using no key.

   JOIN #foo,#bar fubar,foobar     ; Command to join channel #foo using
                                   key "fubar", and channel #bar using
                                   key "foobar".

   JOIN #foo,#bar                  ; Command to join channels #foo and
                                   #bar.

   JOIN 0                          ; Leave all currently joined
                                   channels.

   :WiZ!jto@tolsun.oulu.fi JOIN #Twilight_zone ; JOIN message from WiZ
                                   on channel #Twilight_zone
```

--------------------------------

### USERHOST command example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Example of using the USERHOST command to retrieve information about multiple nicknames. The server returns a space-separated list of replies for each found nickname.

```irc
USERHOST Wiz Michael syrk       ; USERHOST request for information on
                                   nicks "Wiz", "Michael", and "syrk"
```

--------------------------------

### IRC JOIN Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Demonstrates various ways to use the JOIN command to enter channels, with or without keys.

```irc
JOIN #foobar
```

```irc
JOIN &foo fubar
```

```irc
JOIN #foo,&bar fubar
```

```irc
JOIN #foo,#bar fubar,foobar
```

```irc
JOIN #foo,#bar
```

```irc
:WiZ JOIN #Twilight_zone
```

--------------------------------

### SERVER command example (new server registration)

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

A new server introduces itself to the network, providing its name, hop count, and descriptive information. The name in brackets is the hostname of the machine running the server.

```irc
SERVER test.oulu.fi 1 :[tolsun.oulu.fi] Experimental server                                ; New server test.oulu.fi introducing
                                itself and attempting to register.  The
                                name in []'s is the hostname for the
                                host running test.oulu.fi.
```

--------------------------------

### IRC JOIN Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Shows how to use the JOIN command to request entry into an IRC channel. Includes joining a channel and joining with a key.

```irc
JOIN #foobar
```

```irc
JOIN &foo fubar
```

--------------------------------

### USERHOST reply example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Example of a server reply to a USERHOST command, providing information for the nickname 'syrk'.

```irc
:ircd.stealth.net 302 yournick :syrk=+syrk@millennium.stealth.net
                                   ; Reply for user syrk
```

--------------------------------

### SERVER command example (server to server introduction)

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

An existing server introduces another server to the network, indicating its name, hop count from the perspective of the sending server, and descriptive information.

```irc
:tolsun.oulu.fi SERVER csd.bu.edu 5 :BU Central Server                                ; Server tolsun.oulu.fi is our uplink
                                for csd.bu.edu which is 5 hops away.
```

--------------------------------

### REHASH Command Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

An example of an operator command to instruct the server to re-read its configuration file.

```irc
REHASH                          ; message from user with operator
                                   status to server asking it to reread
                                   its configuration file.
```

--------------------------------

### Test-Install irc3 using Pip

Source: https://github.com/gawel/irc3/blob/main/docs/hack.md

Install the irc3 project locally using pip for testing purposes. This command installs from the current directory.

```bash
$ pip install .
$ irc3 -h
```

--------------------------------

### PART Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Illustrates the PART command for leaving one or more channels, optionally with a custom message.

```irc
PART #twilight_zone             ; Command to leave channel
                                   "#twilight_zone"

   PART #oz-ops,&group5            ; Command to leave both channels
                                   "&group5" and "#oz-ops".

   :WiZ!jto@tolsun.oulu.fi PART #playzone :I lost
                                   ; User WiZ leaving channel
                                   "#playzone" with the message "I
                                   lost".
```

--------------------------------

### IRC INVITE Command Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Illustrates the INVITE command used to invite a user to a channel. The first example shows a server-sent message, while the second shows a client command.

```irc
:Angel!wings@irc.org INVITE Wiz #Dust
```

```irc
INVITE Wiz #Twilight_Zone
```

--------------------------------

### Run IRC3 Bot with Configuration File

Source: https://context7.com/gawel/irc3/llms.txt

Basic command to start an IRC3 bot using a specified configuration file.

```bash
irc3 bot.ini
```

--------------------------------

### IRC NICK Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Examples of the NICK command, used to set or change a user's nickname. The first example shows a client setting a nickname, and the second shows a server message indicating a nickname change.

```irc
NICK Wiz                ; Introducing new nick "Wiz" if session is
                          still unregistered, or user changing his
                          nickname to "Wiz"
```

```irc
:WiZ!jto@tolsun.oulu.fi NICK Kilroy
                          ; Server telling that WiZ changed his
                          nickname to Kilroy.
```

--------------------------------

### IRC USER Command Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Example of the USER command used to register a new user with the IRC server, specifying username, mode, and real name.

```irc
USER guest 0 * :Ronnie Reagan   ; User registering themselves with a
```

--------------------------------

### IRC PASS Command Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Example of the PASS command used to set a connection password before registering with an IRC server.

```irc
PASS secretpasswordhere
```

--------------------------------

### NICK command examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Introduces a new nickname or changes an existing one. The first example shows a client introducing itself, while the second shows a server message indicating a nickname change.

```irc
NICK Wiz                        ; Introducing new nick "Wiz".
```

```irc
:WiZ NICK Kilroy                ; WiZ changed his nickname to Kilroy.
```

--------------------------------

### IRC PART Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Shows how to use the PART command to leave one or more channels.

```irc
PART #twilight_zone
```

```irc
PART #oz-ops,&group5
```

--------------------------------

### USERS command example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Example of using the USERS command to request a list of users logged into a specific server. This command should be disabled by default due to security implications.

```irc
USERS eff.org                   ; request a list of users logged in
                                   on server eff.org
```

--------------------------------

### IRC KICK Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Demonstrates the KICK command for removing a user from a channel. Examples include a simple kick, a kick with a reason, and a server-sent kick message.

```irc
KICK &Melbourne Matthew
```

```irc
KICK #Finnish John :Speaking English
```

```irc
:WiZ!jto@tolsun.oulu.fi KICK #Finnish John
```

--------------------------------

### Install older Python 2 version

Source: https://github.com/gawel/irc3/blob/main/docs/index.md

Use this command to install an older version of irc3 if Python 2 is required.

```default
$ pip install "irc3<0.9"
```

--------------------------------

### IRC SQUIT Command Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Illustrates the SQUIT command, used by operators to disconnect server links. Includes examples for terminating a connection with a comment.

```irc
SQUIT tolsun.oulu.fi :Bad Link ?
```

```irc
:Trillian SQUIT cm22.eng.umd.edu :Server out of control
```

--------------------------------

### WALLOPS command example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Example of using the WALLOPS command to send a message to all users with the 'w' mode set. It is recommended that only servers originate WALLOPS messages.

```irc
:csd.bu.edu WALLOPS :Connect '*.uiuc.edu 6667' from Joshua ; WALLOPS
                                   message from csd.bu.edu announcing a
                                   CONNECT message it received from
                                   Joshua and acted upon.
```

--------------------------------

### Install and Run Hupper for File Watching

Source: https://github.com/gawel/irc3/blob/main/docs/reloadable.md

Use `hupper` to automatically restart your bot when configuration files change during development. Install it via pip and run it with your configuration file.

```bash
pip install hupper
hupper -m irc3 config.ini
```

--------------------------------

### USER command example (client registration)

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Used by a client to register itself with the IRC network, specifying username, hostname, servername, and real name. The realname parameter must be the last and prefixed with a colon.

```irc
USER guest tolmoon tolsun :Ronnie Reagan                                   ; User registering themselves with a
                                   username of "guest" and real name
                                   "Ronnie Reagan".
```

--------------------------------

### Create and Run an IrcBot Programmatically

Source: https://context7.com/gawel/irc3/llms.txt

Instantiate IrcBot with configuration parameters like nick, host, and plugins. Call bot.run() to start the bot and enter the asyncio event loop.

```python
import irc3

# Programmatic configuration
bot = irc3.IrcBot(
    nick='mybot',
    username='mybot',
    realname='My irc3 Bot',
    host='irc.libera.chat',
    port=6697,
    ssl=True,
    autojoins=['#mybotchannel'],
    includes=[
        'irc3.plugins.core',
        'irc3.plugins.autojoins',
        'irc3.plugins.userlist',
        'irc3.plugins.command',
        'mymodule',  # your own plugin module
    ],
)
bot.run(forever=True)
```

--------------------------------

### Run IRC3 Bot with Options

Source: https://context7.com/gawel/irc3/llms.txt

Examples of running an IRC3 bot with various command-line options to control verbosity, logging, debugging, and network connection details.

```bash
irc3 --verbose --raw bot.ini          # show all raw IRC traffic
```

```bash
irc3 --debug bot.ini                  # enable debug commands (!quote, !reconnect)
```

```bash
irc3 --host irc.libera.chat --port 6697 bot.ini
```

```bash
irc3 --logdir /var/log/irc3 bot.ini
```

```bash
irc3 --help-page bot.ini > commands.rst  # generate reST command reference
```

--------------------------------

### USER command example (server to server)

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Used between servers to indicate a new user arriving on IRC. The nickname for which the USER command belongs is prefixed to the message.

```irc
:testnick USER guest tolmoon tolsun :Ronnie Reagan                                 ; message between servers with the
                                   nickname for which the USER command
                                   belongs to
```

--------------------------------

### AWAY Command Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Demonstrates setting an AWAY message to inform other users about the client's temporary unavailability.

```irc
AWAY :Gone to lunch.  Back in 5 ; Command to set away message to
                                   "Gone to lunch.  Back in 5".
```

--------------------------------

### List All Channels - LIST

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the LIST command without parameters to get a list of all channels on the server.

```irc
LIST
```

--------------------------------

### IRC QUIT Command Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Demonstrates the QUIT command to terminate a client session. The server acknowledges with an ERROR message.

```irc
QUIT :Gone to have lunch
```

```irc
:syrk!kalt@millennium.stealth.net QUIT :Gone to have lunch
```

--------------------------------

### Create custom async query with AsyncEvents

Source: https://context7.com/gawel/irc3/llms.txt

This example shows how to build a custom awaitable IRC query helper using `AsyncEvents`. It defines the command to send (`send_line`), the regex patterns to collect events (`events`), and an optional method to process results. The `Invite` class waits for an INVITE response or an error code.

```python
from irc3.asynchronous import AsyncEvents
import irc3

class Invite(AsyncEvents):
    """Wait for an INVITE response"""
    timeout = 10
    send_line = 'INVITE {nick} {channel}'
    events = (
        {'match': r'^:\S+ 341 \S+ (?P<nick>\S+) (?P<channel>\S+)', 'final': True},
        {'match': r'^:\S+ (?P<retcode>4\d\d) \S+ .*', 'final': True},
    )
    def process_results(self, results=None, **value):
        for res in results:
            value.update(res)
        value['success'] = 'retcode' not in value
        return value

@irc3.plugin
class InvitePlugin:
    requires = ['irc3.plugins.asynchronious']
    def __init__(self, bot):
        self.bot = bot
        self.invite_cmd = Invite(bot)

    async def invite_and_confirm(self, nick, channel):
        result = await self.invite_cmd(nick=nick, channel=channel)
        if result.get('timeout'):
            self.bot.log.warning('INVITE timed out')
        elif result['success']:
            self.bot.privmsg(channel, f'{nick} has been invited!')
```

--------------------------------

### ERROR Message Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Illustrates an ERROR message sent between servers to indicate an existing server instance.

```irc
ERROR :Server *.fi already exists ; ERROR message to the other server
                                   which caused this error.
```

--------------------------------

### List Specific Channels - LIST

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the LIST command with channel parameters to get information about specific channels.

```irc
LIST #twilight_zone,#42
```

--------------------------------

### Configure and run irc3 FIFO plugin

Source: https://context7.com/gawel/irc3/llms.txt

This snippet shows how to configure and run the irc3.plugins.fifo plugin. It requires specifying a runpath for FIFOs. Examples demonstrate shell usage for sending messages and commands to IRC channels.

```python
from irc3.testing import IrcBot, ini2config

config = ini2config("""
[bot]
includes =
    irc3.plugins.core
    irc3.plugins.fifo
[irc3.plugins.fifo]
runpath = /tmp/run/mybot
""")
bot = IrcBot(**config)

# After bot joins #general, a FIFO appears at /tmp/run/mybot/general
# Shell usage:
#   echo "Deploy complete!" > /tmp/run/mybot/general
#   cat /var/log/deploy.log > /tmp/run/mybot/general
#   echo "JOIN #newchan" > /tmp/run/mybot/:raw
#   echo "NICK newname"  > /tmp/run/mybot/:raw
```

--------------------------------

### MODE Command Examples for Channel Settings

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Shows how to use the MODE command to change channel characteristics like moderation, invite-only status, operator privileges, voice status, secret flag, channel key, and user limits.

```irc
MODE #Finnish +imI *!*@*.fi     ; Command to make #Finnish channel
                                   moderated and 'invite-only' with user
                                   with a hostname matching *.fi
                                   automatically invited.

   MODE #Finnish +o Kilroy         ; Command to give 'chanop' privileges
                                   to Kilroy on channel #Finnish.

   MODE #Finnish +v Wiz            ; Command to allow WiZ to speak on
                                   #Finnish.

   MODE #Fins -s                   ; Command to remove 'secret' flag
                                   from channel #Fins.

   MODE #42 +k oulu                ; Command to set the channel key to
                                   "oulu".

   MODE #42 -k oulu                ; Command to remove the "oulu"
                                   channel key on channel "#42".


   MODE #eu-opers +l 10            ; Command to set the limit for the
                                   number of users on channel
                                   "#eu-opers" to 10.

   :WiZ!jto@tolsun.oulu.fi MODE #eu-opers -l
                                   ; User "WiZ" removing the limit for
                                   the number of users on channel "#eu-
                                   opers".

   MODE &oulu +b                   ; Command to list ban masks set for
                                   the channel "&oulu".

   MODE &oulu +b *!*@*             ; Command to prevent all users from
                                   joining.

   MODE &oulu +b *!*@*.edu +e *!*@*.bu.edu
                                   ; Command to prevent any user from a
```

--------------------------------

### Example bot plugin file

Source: https://github.com/gawel/irc3/blob/main/docs/index.md

This Python code defines a simple IRC bot plugin. It includes an event handler for channel joins and a command that echoes user input.

```default
# -*- coding: utf-8 -*-
from irc3.plugins.command import command
import irc3


@irc3.plugin
class Plugin:

    def __init__(self, bot):
        self.bot = bot

    @irc3.event(irc3.rfc.JOIN)
    def say_hi(self, mask, channel, **kw):
        """Say hi when someone join a channel"""
        if mask.nick != self.bot.nick:
            self.bot.privmsg(channel, 'Hi %s!' % mask.nick)
        else:
            self.bot.privmsg(channel, 'Hi!')

    @command(permission='view')
    def echo(self, mask, target, args):
        """Echo

            %%echo <message>...
        """
        yield ' '.join(args['<message>'])

```

--------------------------------

### DIE Command Example

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Shows the DIE command used by an operator to shut down the server. This command is optional and processed only by the connected server.

```irc
DIE                             ; no parameters required.
```

--------------------------------

### Handle DCC file transfers and chats

Source: https://context7.com/gawel/irc3/llms.txt

This snippet demonstrates how to handle DCC SEND, GET, and CHAT requests using irc3. It includes an event handler for incoming DCC SEND offers and methods for initiating DCC GET and DCC CHAT.

```python
import irc3
from irc3 import dcc_event

@irc3.plugin
class DCCHandler:
    def __init__(self, bot):
        self.bot = bot

    @irc3.event(r'^:(?P<mask>\S+) PRIVMSG \S+ :\x01DCC SEND '
                r'(?P<filename>\S+) (?P<host>\S+) (?P<port>\d+) (?P<size>\d+)\x01')
    async def on_dcc_send_offer(self, mask=None, filename=None,
                                host=None, port=None, size=None, **kw):
        import os
        filepath = os.path.join('/tmp/downloads', filename)
        conn = await self.bot.dcc_get(
            mask, host, int(port), filepath, filesize=int(size))
        self.bot.privmsg(mask.nick, f'Downloaded {filename}!')

    async def send_file_to(self, nick, filepath):
        conn = await self.bot.dcc_send(nick, filepath)
        # conn.ready is already awaited; transfer underway

    async def open_chat(self, nick):
        chat = await self.bot.dcc_chat(nick)
        chat.privmsg('Hello over DCC CHAT!')
```

--------------------------------

### IRC PRIVMSG Command Examples

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Shows various ways to use the PRIVMSG command for sending private messages. Targets can be nicknames, host masks, or server masks.

```irc
:Angel!wings@irc.org PRIVMSG Wiz :Are you receiving this message ?
```

```irc
PRIVMSG Angel :yes I'm receiving it !
```

```irc
PRIVMSG jto@tolsun.oulu.fi :Hello !
```

```irc
PRIVMSG kalt%millennium.stealth.net@irc.stealth.net :Are you a frog?
```

--------------------------------

### Get Channel Creator - MODE

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the MODE command with 'O' to query for the channel creator of a specific channel.

```irc
MODE !12345ircd O
```

--------------------------------

### Set Channel Exception Mask - MODE

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the MODE command to set exception masks for channel joining. This example prevents users from *.edu hostnames, except those from *.bu.edu.

```irc
MODE #bu +be *!*@*.edu *!*@*.bu.edu
```

--------------------------------

### LIST Command

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

The LIST command is used to list channels on the server. It can be used without parameters to list all channels, or with specific channel names to get details about those channels.

```APIDOC
## LIST

### Description
Lists channels on the server. If no parameters are given, all channels are listed. If channel names are provided, details for those specific channels are returned.

### Parameters
* **channel** (string) - Optional - The name of the channel to query.

### Examples
```
LIST
LIST #twilight_zone,#42
```
```

--------------------------------

### View Built Documentation

Source: https://github.com/gawel/irc3/blob/main/docs/hack.md

Open the generated HTML documentation in a web browser. This command assumes you are in the project's root directory.

```bash
$ firefox .tox/docs/tmp/html/index.html
```

--------------------------------

### Create and Run an IrcBot from INI Config

Source: https://context7.com/gawel/irc3/llms.txt

Load bot configuration from an INI file using `IrcBot.from_config`. Ensure the INI file is correctly formatted with a `[bot]` section.

```python
bot = irc3.IrcBot.from_config(irc3.utils.parse_config('bot', 'bot.ini'))
bot.run(forever=True)
```

--------------------------------

### Run IRC3 Bot as Python Module

Source: https://context7.com/gawel/irc3/llms.txt

Demonstrates how to execute the IRC3 bot using the Python module entry point, similar to command-line execution.

```bash
python -m irc3 bot.ini
```

--------------------------------

### Build irc3 Documentation

Source: https://github.com/gawel/irc3/blob/main/docs/hack.md

Generate the project's documentation using tox. This command specifically targets the documentation build process.

```bash
$ tox -e docs
```

--------------------------------

### Generate bot template

Source: https://github.com/gawel/irc3/blob/main/docs/index.md

Use this command to generate a basic bot configuration and plugin file.

```default
$ python -m irc3.template mybot
```

--------------------------------

### Create a new bot directory

Source: https://github.com/gawel/irc3/blob/main/docs/index.md

Commands to create a new directory for your bot and navigate into it.

```sh
$ mkdir mybot
$ cd mybot
```

--------------------------------

### Override irc3 bot configuration with environment variables

Source: https://context7.com/gawel/irc3/llms.txt

This example shows how environment variables can be used to override settings defined in the INI configuration file for an irc3 bot. The format is IRC3_SECTION_KEY=value.

```bash
# Environment variable overrides:
# IRC3_BOT_PASSWORD=value          → [bot] password = value

```

--------------------------------

### List All Visible Channels and Users - NAMES

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the NAMES command without parameters to list all visible channels and their occupants, followed by users not on visible channels.

```irc
NAMES
```

--------------------------------

### Configure SQLite Backend for Storage Plugin

Source: https://context7.com/gawel/irc3/llms.txt

Configure the storage plugin to use an SQLite database for persistent key-value storage. Ensure the 'irc3.plugins.storage' is included in your bot's configuration.

```python
from irc3.testing import IrcBot, ini2config

# SQLite backend
config2 = ini2config("""
[bot]
includes = irc3.plugins.storage
storage = sqlite:///tmp/mybot.sqlite
""")
```

--------------------------------

### Schedule Periodic Tasks with @cron

Source: https://context7.com/gawel/irc3/llms.txt

Use the @cron decorator from irc3.plugins.cron to schedule functions using crontab syntax via aiocron. The decorated function receives the bot as its first argument. Requires `pip install aiocron`.

```python
from irc3.plugins.cron import cron
import irc3

```

--------------------------------

### USER Command

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Specifies the username, hostname, servername, and real name of a new user. It's crucial for user registration alongside the NICK command.

```APIDOC
## USER Command

### Description
Specifies the username, hostname, servername, and real name of a new user. It's crucial for user registration alongside the NICK command.

### Parameters
- **username** (string) - Required - The username of the client.
- **hostname** (string) - Required - The hostname of the client (often ignored for direct clients).
- **servername** (string) - Required - The name of the server the client is connecting to.
- **realname** (string) - Required - The real name of the user, must be prefixed with a colon and can contain spaces.

### Request Example
```
USER guest tolmoon tolsun :Ronnie Reagan
```

### Response
#### Success Response (Implicit)
- User is registered upon successful USER and NICK commands.

#### Error Responses
- ERR_NEEDMOREPARAMS: Not enough parameters provided.
- ERR_ALREADYREGISTRED: The user is already registered.
```

--------------------------------

### Configure Redis Backend for Storage Plugin

Source: https://context7.com/gawel/irc3/llms.txt

Configure the storage plugin to use a Redis instance for persistent key-value storage. Ensure the 'irc3.plugins.storage' is included in your bot's configuration.

```python
from irc3.testing import IrcBot, ini2config

# Redis backend
config3 = ini2config("""
[bot]
includes = irc3.plugins.storage
storage = redis://localhost:6379/0
""")
```

--------------------------------

### Configure irc3 bot using INI file

Source: https://context7.com/gawel/irc3/llms.txt

This INI file demonstrates the configuration of an irc3 bot, including connection details, included plugins, and plugin-specific settings. It also shows how to specify storage URIs and use environment variables for overrides.

```ini
; bot.ini
[bot]
nick = mybot
username = mybot
host = irc.libera.chat
port = 6697
ssl = true
encoding = utf8
flood_burst = 4
flood_rate = 1
autojoins =
    general
    dev
includes =
    irc3.plugins.core
    irc3.plugins.ctcp
    irc3.plugins.autojoins
    irc3.plugins.userlist
    irc3.plugins.command
    irc3.plugins.storage
    mybot_module

[irc3.plugins.command]
cmd = !
antiflood = true
guard = irc3.plugins.command.mask_based_policy

[irc3.plugins.command.masks]
admin!*@trusted.net = all_permissions

[irc3.plugins.storage]
; storage URI: json://, shelve://, sqlite://, redis://
storage = json://${here}/data/bot.json
```

--------------------------------

### Create Bot Commands with @command Decorator

Source: https://context7.com/gawel/irc3/llms.txt

Use the @command decorator to create bot commands. The docstring defines help text and arguments using docopt syntax. Commands can be synchronous or asynchronous, require permissions, be private-only, and support aliases.

```python
from irc3.plugins.command import command
import irc3

@command
def echo(bot, mask, target, args):
    """Echo words back to the channel
        %%echo <words>...
    """
    yield ' '.join(args['<words>'])

# Private-only command with permission requirement
@command(permission='admin', public=False)
def shutdown(bot, mask, target, args):
    """Shut down the bot
        %%shutdown
    """
    bot.quit('Shutting down on admin request')

# Async command (coroutine support)
@command
async def fetch(bot, mask, target, args):
    """Fetch URL title
        %%fetch <url>
    """
    # simulate async work
    import asyncio
    await asyncio.sleep(0.1)
    return [f'Fetched: {args["<url>"]}']

# Command with aliases and custom error format
@command(aliases=['hi', 'hey'], error_format='Usage: %%hello [<name>]'.format)
def hello(bot, mask, target, args):
    """Say hello
        %%hello [<name>]
    """
    name = args.get('<name>') or mask.nick
    yield f'Hello, {name}!'

# --- INI config for command plugin ---
# [irc3.plugins.command]
# cmd = !
# guard = irc3.plugins.command.mask_based_policy
# antiflood = true
#
# [irc3.plugins.command.masks]
# admin!*@* = all_permissions
# trusted!*@* = admin help

```

--------------------------------

### Configure JSON Backend for Storage Plugin

Source: https://context7.com/gawel/irc3/llms.txt

Configure the storage plugin to use a JSON file for persistent key-value storage. Ensure the 'irc3.plugins.storage' is included in your bot's configuration.

```python
from irc3.testing import IrcBot, ini2config

# JSON backend
config = ini2config("""
[bot]
includes = irc3.plugins.storage
storage = json:///tmp/mybot.json
""")
bot = IrcBot(**config)

# Store and retrieve
bot.db['user:alice'] = {'score': 10, 'level': 2}
print(bot.db['user:alice'])           # {'score': 10, 'level': 2}
print('user:alice' in bot.db)         # True

# Safe get with default
data = bot.db.get('user:bob', {'score': 0})

# Partial update (only sets keys not already present)
bot.db.setdefault('user:alice', score=0, title='newcomer')
# => {'score': 10, 'level': 2}  (score unchanged, title added)

# Explicit update
bot.db.set('user:alice', score=15)

# Lists
bot.db.setlist('highscores', ['alice', 'bob', 'charlie'])
print(bot.db.getlist('highscores'))   # ['alice', 'bob', 'charlie']

# Delete
del bot.db['user:alice']
```

--------------------------------

### JOIN Command

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

The JOIN command allows a user to request to join one or more channels. A special argument '0' can be used to leave all channels.

```APIDOC
## JOIN

### Description
Requests to join one or more channels.

### Command
JOIN

### Parameters
- `<channel>` (string) - Required - The channel(s) to join. Can be a comma-separated list.
- `<key>` (string) - Optional - The key for password-protected channels. Can be a comma-separated list corresponding to channels.
- `0` (string) - Special argument to leave all channels.

### Examples
```
JOIN #foobar
```

```
JOIN &foo fubar
```

### Server Response
Upon successful join, the user receives a JOIN message, the channel's topic (RPL_TOPIC), and the list of users on the channel (RPL_NAMREPLY).

### Numeric Replies
- ERR_NEEDMOREPARAMS
- ERR_BANNEDFROMCHAN
- ERR_INVITEONLYCHAN
- ERR_BADCHANNELKEY
- ERR_CHANNELISFULL
- ERR_BADCHANMASK
- ERR_NOSUCHCHANNEL
- ERR_TOOMANYCHANNELS
- ERR_TOOMANYTARGETS
- ERR_UNAVAILRESOURCE
- RPL_TOPIC
```

--------------------------------

### Async IRC Queries with irc3.plugins.asynchronious

Source: https://context7.com/gawel/irc3/llms.txt

Extends the bot with awaitable IRC query helpers for WHOIS, WHO, and NAMES. Each method sends an IRC command and collects the multi-line server response into a structured dictionary. Requires 'irc3.plugins.asynchronious' to be included.

```python
import irc3
from irc3.plugins.command import command

@irc3.plugin
class InfoPlugin:
    requires = ['irc3.plugins.asynchronious']

    def __init__(self, bot):
        self.bot = bot

    @command
    async def whois(self, mask, target, args):
        """Whois a user
            %%whois <nick>
        """
        result = await self.bot.async_cmds.whois(args['<nick>'])
        if result.get('timeout'):
            yield f'{args["<nick>"]} timed out'
            return
        channels = ', '.join(result.get('channels', []))
        idle = int(result.get('idle', 0)) // 60
        yield f'{args["<nick>"]} — idle {idle}m, on: {channels}'

    @command
    async def chaninfo(self, mask, target, args):
        """Show channel info
            %%chaninfo <channel>
        """
        names = await self.bot.async_cmds.names(args['<channel>'])
        who = await self.bot.async_cmds.who(args['<channel>'])
        yield f'{args["<channel>"]}: {len(names["names"])} nicks, {len(who["users"])} with host info'

    @command
    async def seen(self, mask, target, args):
        """Check if nick is online
            %%seen <nick>
        """
        result = await self.bot.async_cmds.ison(args['<nick>'])
        if args['<nick>'].lower() in [n.lower() for n in result['names']]:
            yield f'{args["<nick>"]} is currently online'
        else:
            yield f'{args["<nick>"]} is not online'
```

--------------------------------

### Run All Tox Tests

Source: https://github.com/gawel/irc3/blob/main/CONTRIBUTING.rst

Execute all test environments defined in tox. This is a comprehensive check to ensure your changes haven't broken anything.

```bash
$ tox
...
py27: commands succeeded
py32: commands succeeded
py33: commands succeeded
py34: commands succeeded
flake8: commands succeeded
docs: commands succeeded
congratulations :)
```

--------------------------------

### Send a notice to a user

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Used similarly to PRIVMSG, but automatic replies are not permitted. This helps prevent loops between automatons.

```irc
NOTICE WiZ :This is a notice message.
```

--------------------------------

### List Channel Invitation Masks - MODE

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the MODE command with 'I' to list invitation masks for a channel. This shows which users are explicitly invited.

```irc
MODE #meditation I
```

--------------------------------

### List Channel Exception Masks - MODE

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the MODE command with 'e' to list exception masks for a channel. This shows which hostnames are excluded from joining.

```irc
MODE #meditation e
```

--------------------------------

### Creating Bot Commands with @command

Source: https://context7.com/gawel/irc3/llms.txt

The @command decorator from irc3.plugins.command allows you to create command handlers for your bot. These commands can be synchronous or asynchronous, support aliases, and have their help text and argument specifications defined using docopt syntax.

```APIDOC
## @command — Creating Bot Commands

The `@command` decorator (from `irc3.plugins.command`) creates `!command` handlers. The docstring serves as both help text and argument spec via [docopt](http://docopt.org/) syntax — lines starting with `%%` define usage. Commands can be sync or `async`, can require permissions, be restricted to private messages, and support aliases.

```python
from irc3.plugins.command import command
import irc3

@command
def echo(bot, mask, target, args):
    """Echo words back to the channel
        %%echo <words>...
    """
    yield ' '.join(args['<words>'])

# Private-only command with permission requirement
@command(permission='admin', public=False)
def shutdown(bot, mask, target, args):
    """Shut down the bot
        %%shutdown
    """
    bot.quit('Shutting down on admin request')

# Async command (coroutine support)
@command
async def fetch(bot, mask, target, args):
    """Fetch URL title
        %%fetch <url>
    """
    # simulate async work
    import asyncio
    await asyncio.sleep(0.1)
    return [f'Fetched: {args["<url>"]}']

# Command with aliases and custom error format
@command(aliases=['hi', 'hey'], error_format='Usage: %%hello [<name>]'.format)
def hello(bot, mask, target, args):
    """Say hello
        %%hello [<name>]
    """
    name = args.get('<name>') or mask.nick
    yield f'Hello, {name}!'
```
```

--------------------------------

### INVITE Command

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

The INVITE command is used to invite a user to a specific channel. The inviting client must be a channel operator if the channel is invite-only.

```APIDOC
## INVITE

### Description
Invites a user to a channel. The target channel does not need to exist, and the inviting user must be an operator if the channel is invite-only.

### Parameters
* **nickname** (string) - Required - The nickname of the user to invite.
* **channel** (string) - Required - The name of the channel to invite the user to.

### Examples
```
:Angel INVITE Wiz #Dust
INVITE Wiz #Twilight_Zone
```
```

--------------------------------

### INVITE Command

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

The INVITE command is used to invite a user to a channel. Only members of a channel or channel operators (if the channel is invite-only) can issue this command.

```APIDOC
## INVITE Command

### Description
Used to invite a user to a channel.

### Parameters
- **<nickname>**: The nickname of the user to invite.
- **<channel>**: The target channel to invite the user to.

### Examples
```
INVITE &numpy $~1
```
```

--------------------------------

### Configure Autojoins Plugin with Channel Passwords

Source: https://context7.com/gawel/irc3/llms.txt

Configure the autojoins plugin to automatically join specified channels upon server connection. Channel passwords can be provided using the 'passwords' dictionary.

```python
from irc3.testing import IrcBot

bot = IrcBot(
    nick='mybot',
    autojoins=['#general', '#dev', 'ops'],  # '#' prefix added automatically
    autojoin_delay=2,  # seconds to wait after MOTD before joining
    includes=['irc3.plugins.core', 'irc3.plugins.autojoins'],
    passwords={'#private': 'secretpass'},  # channel passwords
)

# --- INI equivalent ---
# [bot]
# autojoins =
#     general
#     dev
#     ops
# autojoin_delay = 2
# includes =
#     irc3.plugins.core
#     irc3.plugins.autojoins
```

--------------------------------

### Run irc3 bot

Source: https://github.com/gawel/irc3/blob/main/docs/index.md

Command to run the irc3 bot using its configuration file.

```sh
$ irc3 config.ini
```

--------------------------------

### View Channel Topic - TOPIC

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the TOPIC command without a topic parameter to view the current topic of a channel.

```irc
TOPIC #test
```

--------------------------------

### Run irc3 in Debug Mode

Source: https://github.com/gawel/irc3/blob/main/docs/hack.md

Use this command to run irc3 with debug logging enabled. Specify the path to your configuration file.

```bash
$ irc3 --debug path-to-your-conf.ini
```

--------------------------------

### USER Command

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Registers a user with the IRC server, specifying username, real name, and optional invisibility.

```APIDOC
## USER Command

### Description
Registers a user with the IRC server. Allows specifying a username and real name.

### Parameters
- **username** (string) - Required - The username for the client.
- **mode** (string) - Optional - User modes to set (e.g., 'i' for invisible).
- **unused** (string) - Unused parameter, typically '*'.
- **realname** (string) - Required - The real name of the user.

### Example
```
USER guest 0 * :Ronnie Reagan
```
```

--------------------------------

### List Visible Users on Specific Channels - NAMES

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the NAMES command with channel parameters to list visible users on those specific channels.

```irc
NAMES #twilight_zone,#42
```

--------------------------------

### VERSION Command

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

The VERSION command queries the version of the server program. It can be used to query the version of the local server or a remote server.

```APIDOC
## VERSION

### Description
Queries the version of the server program. An optional server parameter can be used to query the version of a server the client is not directly connected to.

### Parameters
* **server** (string) - Optional - The name of the server to query.

### Examples
```
:Wiz VERSION *.se
VERSION tolsun.oulu.fi
```
```

--------------------------------

### Invite User to Channel - INVITE

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc2812.txt

Use the INVITE command to invite a specified nickname to a target channel. Channel operators may issue this command on invite-only channels.

```irc
INVITE <nickname> <channel>
```

--------------------------------

### Query user information

Source: https://github.com/gawel/irc3/blob/main/irc3/rfc1459.txt

Generates a query to list information matching the provided name. If no name is given, all visible users are listed. The name is matched against host, server, real name, and nickname.

```irc
WHO *.fi
```

```irc
WHO jto* o
```