Command-line searches

The aox show search command parses a search expression and displays its meaning. It is intended for debugging search expressions.

aox show search from easydns.com and subject renewal
All must be true:
  From address has domain "easydns.com"
  Subject field contains string "renewal"

The same search syntax is used in several other aox commands, such as aox add view and aox undelete.

Search syntax

The search syntax used is optimised to be easy to write in the unix shell. It's easy to write, avoids some common problems, doesn't need too much quoting, but has some unnecessary limitations.

We think that most useful searches can be expressed. We'll happily extend it if something useful is difficult to express, just send mail to info@aox.org.

Addresses are supported in two forms, namely complete addresses and domains. Both are case insensitive. This finds all mail from oryx.com (but not from oryx.com.au, noryx.com or stuff.oryx.com):

aox show search from oryx.com

The next example finds all mail from info@oryx.com (or Info@Oryx.Com, or Oryx <info@oryx.com>, but not from misinfo@oryx.com):

aox show search from info@oryx.com

(This example also shows a typical limitation: You cannot search for addresses case sensitively. The search above will match INFO@oryx.com, and there is no way to change that.)

You can search for addresses in the from, to, cc or reply-to fields, as well as anywhere:

aox show search to info@oryx.com

aox show search cc info@oryx.com

aox show search reply-to info@oryx.com

aox show search address info@oryx.com

Perhaps confusingly, the address key can also work with domains, so this finds all mail to/from/reply-to/… oryx.com:

aox show search address oryx.com

Header fields other than address fields are only partly supported. You can search for the presence of any string in about a dozen well-known fields, and as well as in any field.

This example matches messages whose subject contains the word Alice, but also messages with subject Malice.

aox show search subject Alice

The other fields supported are Comments, Content-Description, Content-Language. Content-Type, Date, In-Reply-To, Keywords, Received and References. The keyword for anywhere is header:

aox show search header Outlook

Boolean logic is fully supported. This example matches messages from alice@example.org with cc to bob@example.com:

aox show search from alice@example.org and cc bob@example.com

You can also match messages that are from either Alice or Bob:

aox show search from alice@example.org or from bob@example.com

This example matches messages that are not from Alice:

aox show search not from alice@example.org

If you want to use and, or and not together, you have to indicate precedence explicitly (because ordering mistakes are a frequent source of error). This example matches messages that don't mention Bob either as To or as Cc:

aox show search not '(' to bob@example.com or cc bob@example.com ')'

(The parentheses are quoted only because bash/zsh demands it.) The parenthesis are only needed where they help avoid errors, so this is legal:

aox show search to bob@example.com and not from alice@example.com

Body text can be searched using the text key:

aox show search text JFIF

Archiveopteryx searches text, not binary data. Even though every JPEG picture contains the four bytes JFIF, the search above will not match JPEGs.

Message age is expressible as a number of days:

aox show search younger 185 and from example.org

aox show search older 185

Message age is a fuzzy concept. While Archiveopteryx has an unambiguous definition, you may find that older 200 matches a message you consider to be 199¾ days old, or doesn't match one you consider to be 201 days old.

If a message has been deleted, then its message age is based on when it was deleted, otherwise it's based on when it was inserted into the database.

Message flags (alias tags) use the flag key:

aox show search flag seen

aox show search not flag answered

The first example shows all read mail, the second shows all unanswered mail. Both are slightly unreliable, since the message flags can be changed at will. One does not have to set the Answered flag when answering mail, and one can set it without answering.

Some other possibilities we've considered:

We have not considered any specific syntax yet.

Executing searches

At present show search can only show searches. At some future date we want to extend the command so it can display the SQL query that would be used and perhaps even execute it and display its results.

The aoxexport program executes a search and returns the matching messages.

In case of questions, please write to info@aox.org.

Relevant links

About this page

Last modified: 2010-11-19
Location: aox.org/aox/showsearch