REVIEW · TERMINAL COMMAND
Verdict: mdfind is the most precise way to ask Spotlight a question: it is free, built into macOS, scriptable, and its query language can match any metadata attribute with wildcards, case options and dates. It is a Terminal tool for people comfortable with syntax, and it can only find what Spotlight's metadata store holds.
25 October 2026 · By Ishtiaque Hossain · 4 minute read
Looking for a file you can describe but not name? Try Shlexball. The first 30 searches are free and need no account.
macOS 15 or later. Apple silicon. 16 GB memory. On a phone? Email yourself the link.
This review is based on mdfind's own pages, read on 14 October 2026. Every claim links to the page it came from. We are the makers of Shlexball, so we say plainly where mdfind does better.
| Price | Built into macOS; you run it in Terminal |
| What it searches | The central metadata store, the same data Spotlight uses |
| Key options | -onlyin to limit the folder, -name for file names, -live, -count, -0 |
| Query syntax | attribute == value, with wildcards, case and accent modifiers, AND, OR and date variables |
| Best for | Scripts and precise searches by people at ease in Terminal |
mdfind is the command-line face of Spotlight. Its manual describes it in one line: it finds files matching a given query, by consulting the central metadata store and returning a list of matching files.
Metadata here means everything Spotlight records about a file: its name, its kind, its author, dates, and for many documents the text inside. Apple's query documentation uses the same examples to query Spotlight itself.
Spotlight in the menu bar is built for quick, interactive searches with results as you type. mdfind gives you the same underlying data as plain text in Terminal, which you can count, filter or pass to other commands.
The simplest search is a word: mdfind image returns every file with any metadata value matching image. That is broad, so the options matter.
-onlyin limits the search to one folder, -name searches file names only, and -count prints the number of matches instead of the list. -live keeps the search running and updates the count as files change until you press Control-C.
-0 ends each result with a special null character so you can pipe paths safely into xargs -0, and -interpret treats your words as if you had typed them into the Spotlight menu.
To see which metadata attributes exist on your Mac, the manual points you to mdimport with its -X switch.
Real power comes from query expressions of the form attribute == value. Apple's example finds every file authored by Steve with kMDItemAuthors ==[c] "Steve", where [c] makes the match case insensitive and [d] would ignore accents.
Comparisons include equal, not equal, greater and less than for numbers and dates, and InRange for a span of values. The wildcards * and ? match many characters or one character, so kMDItemTextContent == "*paris*" finds paris anywhere in a file's text.
Combine conditions with && for AND and || for OR, and group them with parentheses, for example to find audio or video files by either of two authors.
Dates use the $time variable: $time.today, $time.this_week(-1) for last week, $time.this_month and more. Apple notes that $time is fixed when the query starts and does not move forward while a live search runs.
mdfind is exact. If you know an attribute and a value, such as an author, a content type or a date range, it returns precisely the files that match, which is ideal inside scripts and automations.
The flip side is that it answers only what the metadata store contains and only the question you can express. A vague memory of what a document discussed is hard to turn into kMDItemTextContent wildcards.
The documentation is also old. The manual page is dated 2004 and Apple's query syntax guide was last updated in 2011, though both still describe how the command works.
Developers, system administrators and anyone writing automations should know mdfind, especially -onlyin, -name and -count.
Everyone else will find the same data easier to reach through Spotlight itself, opened with Command-Space bar.
Shlexball is for the searches mdfind makes hard: you describe the file in plain English and it finds it from what you remember, searching file and folder names and the text inside files, including PDFs and Word documents.
It searches your folders directly, not only through the Spotlight index, runs its language model on your Mac and never changes, moves or deletes files. The first 30 searches are free.
Shlexball writes the read-only search for you and shows it in Search details: 30 free searches.
▶ DOWNLOAD SHLEXBALLmdfind consults the central metadata store, the data behind Spotlight, and lists the files that match your query. You run it in Terminal.
Add -onlyin and the folder, for example mdfind -onlyin ~/Documents invoice. Use -name to match file names only.
Yes, through the kMDItemTextContent attribute, for example kMDItemTextContent ==[c] "*paris*" for case-insensitive text anywhere in a file.
mdfind returns only what the central metadata store contains, so a file Spotlight has not indexed will not appear. Try -name for a name search and check the folder with -onlyin.