|QUARG(1)||General Commands Manual||QUARG(1)|
quargsearches 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,
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
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
- Interprets any keyword as a LIKE
expression. This allows the use of the ‘%’ placeholder. If
no placeholders are given, matches the keyword
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
-lnum, as it may be used to have
quarglimit output to the oldest (asc) or most recent (desc) num matches.
- Shows the integrated help page and exits.
- 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 of the Modern IRC Client Protocol
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
This condition is only useful if the Quassel database contains logs for multiple Quassel users. Without this condition,
quargmatches 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: invite, join, kick, kill, mode, nick, notice, part, privmsg, quit, topic.
quargsupports 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
quarg supports matching on
message timestamps. Wherever a date is passed as an argument to a condition,
quarg parses it according to the
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 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
- Matches messages that were sent before date.
quargneeds 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 uses SQLAlchemy which supports both
SQLite and PostgreSQL backends. The psycopg2 backend is recommended for the
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 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 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+psycopg2://quarg@/quassel?host=/run/postgresql
- The configuration file for
quarg adheres to the XDG Base Directory
Specification. If $XDG_CONFIG_HOME is unset or empty, it will default to
- Channel Membership Prefixes
- RFC 1459
- dateutil isoparse
- Peer Authentication
- Database URLs
quargwas written by Wolfgang Müller
|May 8, 2021|