mdfind

Spotlight search

Syntax
      mdfind [-live] [-count] [-onlyin directory] query

Key
    query       A string or query expression.

    -0          Print an ASCII NUL character after each result path.
                This is useful when used in conjunction with xargs -0.

    -live       Causes the mdfind command to provide live-updates to the 
                number of files matching the query.  When an update causes the
                query results to change the number of matches is updated.
                The find can be cancelled by typing ctrl-C.

    -count      Output the total number of matches, instead of the path 
                to the matching items.

    -onlyin dir
                Limit the scope of the search to the directory specified.

    -literal    Force the provided query string to be taken as a literal
                query string, without interpretation.

    -interpret  Force the provided query string to be interpreted as if the
                user had typed the string into the Spotlight menu.
                For example, the string "search" would produce the following 
                query string:
                       (* = search* cdw || kMDItemTextContent = search* cdw)

Spotlight Keywords.

These can be included in the query expression to limit the type of documents returned:

Applications kind:application, kind:applications, kind:app
Audio/Music kind:audio, kind:music
Bookmarks kind:bookmark, kind:bookmarks
Contacts kind:contact, kind:contacts
Email kind:email, kind:emails, kind:mail message, kind:mail messages
Folders kind:folder, kind:folders
Fonts kind:font, kind:fonts
iCal Events kind:event, kind:events
iCal To Dos kind:todo, kind:todos, kind:to do, kind:to dos
Images kind:image, kind:images
Movies kind:movie, kind:movies
PDF kind:pdf, kind:pdfs
Preferences kind:system preferences, kind:preferences
Presentations kind:presentations, kind:presentation

Date Keywords.

These can be included in the query expression to limit the age of documents returned:

date:today    $time.today()
date:yesterday .yesterday()
date:this week  .this_week()
date:this month .this_month()
date:this year  .this_year()

date:tomorrow  .tomorrow()
date:next month  .next_month()
date:next week  .next_week()
date:next year  .next_year()

Boolean Operators

By default mdfind will AND together elements of the query string.
| (OR) To return items that match either word, use the pipe character: stringA|stringB
- (NOT) To exclude documents that match a string -string
== “equal”
!= “not equal”
< and > “less” or “more than”
<= and >= “less than or equal” or “more than or equal”
Whitespace is significant when building a query, use brackets () to create groups.

To get a list of the available attributes for use in constructing queries, see mdimport(1), particularly the -X switch. Not all files are indexed by spotlight and not all file attributes are present on all files, image files, iCal files and music files all support different attributes.

Examples

Returns all files with any metadata attribute value matching the string "image":

$ mdfind image

Return all files that contain "Len Deighton" in the kMDItemAuthor metadata attribute:

$ mdfind "kMDItemAuthor == '*Len Deighton*'"

Return all files with any metadata attribute value matching the string "skateboard". The find continues to run after gathering the initial results, providing a count of the number of files that match the query.

$ mdfind -live skateboard

Return all Microsoft.Word document files:

$ mdfind "kMDItemContentType == 'com.microsoft.word.doc'"

Return files where the composer name includes 'Eno' (non case sensitive search):

$ mdfind 'kMDItemComposer = "*ENO*"c'

Return all image files matching the words 'maude' and 'paris':

$ mdfind "kind:images maude paris"

Return all image files last edited yesterday:

$ mdfind "kind:image date:yesterday"

Return all files in the users home folder (~) that have been modified in the last 3 days:

$ mdfind -onlyin ~ 'kMDItemFSContentChangeDate >= $time.today(-3)'

“The real voyage of discovery consists not in seeking new landscapes but in having new eyes” ~ Marcel Proust

Related:

mdfind man page - Apple.com
Spotlight Metadata Attributes - List of all the kDM* attributes (or just use mdls to list the attributes of a file)
mdls - List the Spotlight metadata attributes for a specified file
mdutil - Manage Spotlight metadata store
mdimport - Import file hierarchies into the Spotlight datastore
find - Search for files that meet a desired criteria