The Limitations of the Find Command
When working in the macOS terminal, the standard UNIX tool for locating files is the find command. While powerful, find operates by crawling through every single directory on your hard drive sequentially. If you have a massive 2TB drive packed with project files, running a find command can take several minutes to complete.
macOS, however, possesses a massive advantage over standard Linux distributions: the Spotlight indexing engine. Spotlight constantly runs in the background, maintaining a real-time, highly optimized database of every file, its metadata, and even its contents.
When you press Command+Space and search for a file, the results are instantaneous because the GUI is querying the index, not crawling the drive.
You can tap into this exact same lightning-fast index directly from the terminal using the Metadata Find command: mdfind.
Step 1: The Basic Search
To perform a basic search for a filename, simply type mdfind followed by your query. It behaves exactly like typing the query into the Spotlight search bar.
mdfind "Budget_Report"
Unlike the traditional find command, this will return the absolute paths to every file containing “Budget_Report” in a fraction of a second, regardless of where they are buried on the hard drive.
Step 2: Searching File Contents
Because Spotlight indexes the actual text inside documents (PDFs, Word documents, text files), you can use mdfind to find files based on what is written inside them, not just their filename.
If you know you wrote a document mentioning “Project Apollo” but forgot the filename, you can search the entire hard drive instantly:
mdfind "Project Apollo"
If you want to strictly restrict the search to the filename only (ignoring the contents of the files), use the -name flag:
mdfind -name "Q3_Earnings"
Step 3: Restricting the Search Directory
By default, mdfind searches the entire global Spotlight index (every drive connected to your Mac). This often returns too much noise.
To restrict the search to a specific directory tree (e.g., only search within your “Documents” folder), use the -onlyin flag followed by the path.
mdfind -onlyin ~/Documents "Invoice"
Step 4: Advanced Metadata Queries
The true power of mdfind lies in its ability to query the deep, hidden metadata tags that macOS attaches to files.
You can construct complex queries using the kMDItem attribute syntax. This allows you to filter searches with incredible precision.
For example, to find every single audio file on your hard drive where the embedded metadata indicates the author/artist is “Mozart”, you can run:
mdfind "kMDItemAuthors == '*Mozart*'"
To find every single photograph (JPEG) taken by a specific camera model (e.g., an iPhone 14 Pro), you can query the EXIF data directly from the terminal:
mdfind "kMDItemAcquisitionModel == 'iPhone 14 Pro'"
To discover exactly which hidden metadata tags are available for querying on a specific file, you can inspect it using the sister command, mdls (Metadata List):
mdls ~/Desktop/sample_photo.jpg
This will print out a massive list of attributes (pixel height, latitude, longitude, color space) that you can subsequently use in your mdfind queries to build incredibly fast, highly specific file finding scripts.