QUARG(1) General Commands Manual QUARG(1)

search Quassel logs for matching messages and print them

quarg [-de] [-l num] [-o order] [-b buffer] [-B buftype] [-f msgflag] [-m prefix] [-n nick] [-N network] [-Q user] [-t msgtype] [--after date] [--around date[/range]] [--before date] [--joined | --no-joined] [keyword [keyword ...]]

quarg -h | --help

quarg searches Quassel logs for messages matching a set of conditions and prints the results. See CONNECTING TO QUASSEL for more information on how to set up the database connection.

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:

Prints additional debug information. This includes the SELECT statements executed by SQL as well as an internal representation of the conditions passed to quarg.
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.

Limits the number of matches to num.
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.

Shows the integrated help page and exits.

The conditions are as follows:
Matches messages containing keyword.
Matches messages in a specific buffer, given by its name as displayed in the Quassel client.
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.

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

The flag names are as follows:

Messages that triggered Quassel's “Remote Highlight” rules. By default this includes messages containing the current nickname.
Messages that do not have any flag set.
Messages that were sent by Quassel users themselves.
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.

Matches messages sent by a specific user, given by nickname.
Matches messages in a specific network, given by its name as displayed in the Quassel client.
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.

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:

The CTCP ACTION message.
Error messages as reported to the user by Quassel.
Messages indicating the end of a netsplit, along with the users who rejoined.
Messages indicating an ongoing netsplit, along with the users who quit.
Server messages as reported to the user by Quassel.
Matches messages in channels that are currently 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:

Matches messages that were sent after date.
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.

Matches messages that were sent before date.

In order to access Quassel's logs, quarg needs access to the Quassel database. The easiest way to achieve this is to have it running on the database host and remotely invoke it using ssh(1). Alternatively, the database port (or socket) may be forwarded to a local machine via ssh(1) and used with a local quarg instance.

quarg uses SQLAlchemy which supports both SQLite and PostgreSQL backends. The psycopg2 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:

url = postgresql+psycopg2://quarg@/quassel?host=/run/postgresql

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

  1. Channel Membership Prefixes


  2. RFC 1459


  3. dateutil isoparse


  4. Peer Authentication


  5. Database URLs


quarg was written by Wolfgang Müller
May 8, 2021