NAME

SYNOPSIS

DESCRIPTION

A condition is any option from the CONDITIONS section. At least one condition needs to be specified. If multiple different types of conditions are given, all of them must match. The same condition can be specified multiple times with different arguments, in which case it matches any of the arguments.

If there are any results, quarg prints each match using Quassel's message format, prefixed with the timestamp in local time and the origin buffer of the message separated by the tab character.

The options are as follows:

-d

Prints additional debug information. This includes the SELECT statements executed by SQL as well as an internal representation of the conditions passed to quarg.

-e

Interprets any keyword as a LIKE expression. This allows the use of the ‘%’ placeholder. If no placeholders are given, matches the keyword exactly.

To match ‘%’ literally, escape it with a backslash character.

-l num

Limits the number of matches to num.

-o order

Specifies in which order to sort the messages. Matches are always sorted by timestamp. order can be asc for ascending order or desc for descending order. The default is asc.

This option is useful in conjunction with -l num, as it may be used to have quarg limit output to the oldest (asc) or most recent (desc) num matches.

-h | --help

Shows the integrated help page and exits.

CONDITIONS

keyword

Matches messages containing keyword.

-b buffer

Matches messages in a specific buffer, given by its name as displayed in the Quassel client.

-B buftype

Matches messages in buffers of a specific type.

buftype can be one of channel, query, or status, for channels, queries, and the status (or “network”) buffers respectively.

-f msgflag

Matches messages of a specific context, given by a flag name.

The flag names are as follows:

highlight

Messages that triggered Quassel's “Remote Highlight” rules. By default this includes messages containing the current nickname.

none

Messages that do not have any flag set.

self

Messages that were sent by Quassel users themselves.

-m prefix

Matches messages sent by nicknames that have a specific channel membership prefix as defined in the Channel Membership Prefix section[1] of the Modern IRC Client Protocol specification.

Common prefixes include ‘@’ for operators, ‘%’ for half-ops, and ‘+’ for voiced users.

Note that multiple prefixes may be set at the same time (for example a voiced operator). In this case, any prefix will match, but the printed message will only show the “highest” one.

-n nick

Matches messages sent by a specific user, given by nickname.

-N network

Matches messages in a specific network, given by its name as displayed in the Quassel client.

-Q user

Matches messages relating to a specific Quassel user, given by their user name.

This condition is only useful if the Quassel database contains logs for multiple Quassel users. Without this condition, quarg matches messages from any Quassel user.

-t msgtype

Matches messages of a specific type.

msgtype can be one of the following, corresponding to IRC messages as defined in RFC 1459[2]: invite, join, kick, kill, mode, nick, notice, part, privmsg, quit, topic.

In addition, quarg supports the following message types:

action

The CTCP ACTION message.

error

Error messages as reported to the user by Quassel.

netsplit_join

Messages indicating the end of a netsplit, along with the users who rejoined.

netsplit_quit

Messages indicating an ongoing netsplit, along with the users who quit.

server

Server messages as reported to the user by Quassel.

--joined

Matches messages in channels that are currently joined.

--no-joined

Matches messages in channels that are currently not joined.

Note that as a result of the implementation in Quassel, this condition matches all query buffers. If this is undesirable, combine this condition with -B channel.

In addition, quarg supports matching on message timestamps. Wherever a date is passed as an argument to a condition, quarg parses it according to the ISO-8601 standard.

A date may include a time element and a time zone offset. If no time zone offset is given, the date is assumed to be in local time. Refer to dateutil's isoparse documentation[3] for detailed information.

The conditions that match on message timestamps are as follows:

--after date

Matches messages that were sent after date.

--around date[/range]

Matches messages sent after date - range and before date + range. If range is not given, defaults to 12 hours.

range consists of a number and an optional suffix ‘h’ for hours or ‘m’ for minutes. If no suffix is given, defaults to hours.

For example, “2021-02-18 20:55Z/10m” matches messages sent between 20:45 and 21:05. This is equivalent to the following:

quarg --after '2021-02-18 20:45Z' --before '2021-02-18 21:05Z'
    

This option cannot be used with --after or --before.

--before date

Matches messages that were sent before date.

CONNECTING TO QUASSEL

quarg uses SQLAlchemy which supports both SQLite and PostgreSQL backends. The psycopg backend is recommended for the latter.

If Quassel uses the PostgreSQL backend, it is highly recommended to set up a read-only database role specifically for quarg. Furthermore, consider using the Peer Authentication[4] method with a dedicated user. This type of authentication removes the need for a password and also works over a forwarded connection.

quarg reads the database URL from an INI-style configuration file. See FILES for the location of this file. The URL is specified in the Database section using the url key. See Database URLs[5] for details on the URL format.

The following is a valid configuration file specifying a connection to a local PostgreSQL instance via its default socket:

[Database]
url = postgresql+psycopg://quarg@/quassel?host=/run/postgresql

FILES

$XDG_CONFIG_HOME/quarg/config

The configuration file for quarg.

quarg adheres to the XDG Base Directory Specification. If $XDG_CONFIG_HOME is unset or empty, it will default to ~/.config

NOTES

1. Channel Membership Prefixes

   https://modern.ircdocs.horse/#channel-membership-prefixes

2. RFC 1459

   https://tools.ietf.org/html/rfc1459

3. dateutil isoparse

   https://dateutil.readthedocs.io/en/stable/parser.html#dateutil.parser.isoparse

4. Peer Authentication

   https://www.postgresql.org/docs/13/auth-peer.html

5. Database URLs

   https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls

AUTHORS