Quick reference guide for using `mdfind, the command-line interface to Spotlight on macOS.

Table of Contents

Basic Usage

Search by keyword:

mdfind "search term"

Search in a specific folder:

mdfind -onlyin /path/to/folder "search term"

List all indexed files:
mdfind ""

Metadata Search

Search by metadata:
mdfind 'kMDItemKind == "PDF"'

Combine metadata and keyword:
mdfind 'kMDItemKind == "PDF" && kMDItemTextContent == "*invoice*"'

Common Metadata Attributes

kMDItemDisplayName: File name

kMDItemTextContent: Full text

kMDItemContentType: UTI (e.g., public.jpeg)

kMDItemKind: Human-readable type (e.g., "PDF")

kMDItemKind values are derived from file metadata and can vary based on file type and system settings. Common examples include:

"Alias"
"Folder"
"JPEG Image"
"PNG Image"
"PDF Document"
"Plain Text Document"
"Rich Text Document"
"Microsoft Word Document"
"Microsoft Excel Spreadsheet"
"Audio File"
"Video File"

To determine the kMDItemKind of a specific file, use the mdls command:

mdls /path/to/file

kMDItemAuthors: Document author

kMDItemWhereFroms: Download source

Date Filtering

Files modified after a date:

mdfind 'kMDItemFSContentChangeDate >= $time.iso(2024-01-01T00:00:00Z)'

Limit Results

Limit to first N results:

mdfind -count "search term" # just counts
mdfind "search term" | head -n 10

Exclude Paths (not directly supported)

Use grep:

mdfind "search term" | grep -v "/path/to/exclude"

See All Metadata for a File