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()

Comparison 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”
== “equal”
!= “not equal”
< and > “less” or “more than”
<= and >= “less than or equal” or “more than or equal”
InRange(attributeName,minValue,maxValue) Numeric values within the range of minValue to maxValue in the specified attribute.

Whitespace is significant when building a query, use parentheses () to create groups.
Characters such as “ and ‘ in the value string should be escaped using the \ character

Value Comparison modifiers

Modifier	Description
c	The comparison is case insensitive.
d	The comparison is insensitive to diacritical marks.

kMDItemAuthors ==[c] "Steve"

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 files with the filename 'readme.txt':

$ mdfind -name readme.txt

Count the number of files with the filename 'readme.txt':

$ mdfind -name readme.txt -count

Return all the files that have been tagged as 'Green':

$ mdfind "kMDItemUserTags = Green"

Return all the documents created with any version of Pixelmator:

$ mdfind "kMDItemCreator = Pixelmator*"

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)'

Return all the 32 bit application files (With macOS Catalina, Apple no longer supports 32-bit applications):

$ mdfind "kMDItemExecutableArchitectures == 'i386' && kMDItemExecutableArchitectures != 'x86_64' && kMDItemKind == 'Application'"

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

Related macOS commands

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.