mdfind 🔍

macOS Spotlight as a terminal tool. Fuzzy & exact search across your entire computer in real time.

No RAG. No external tools. No prescriptive structure. Built-in and optimized.

Source: @_chenglou

Why Use This

• •Instant — Spotlight index is always up to date
• •Comprehensive — Searches file names, contents, and metadata
• •Zero setup — Already on every Mac
• •Fast — Highly optimized native search

Basic Usage

# Simple text search (fuzzy, searches content + names)
mdfind "statistical learning"

# Search in specific folder only
mdfind -onlyin ~/clawd "pipeline"

# Live search (updates as files change)
mdfind -live "TODO"

File Type Filters

# PDFs only
mdfind "kMDItemContentType == 'com.adobe.pdf'"

# Markdown files
mdfind "kMDItemContentType == 'net.daringfireball.markdown'"

# Images
mdfind "kMDItemContentType == 'public.image'"

# Python files
mdfind "kMDItemFSName == '*.py'"

# Word documents
mdfind "kMDItemContentType == 'org.openxmlformats.wordprocessingml.document'"

Combining Queries

# PDF containing "methods"
mdfind "kMDItemContentType == 'com.adobe.pdf' && kMDItemTextContent == '*methods*'"

# Markdown files modified today
mdfind "kMDItemContentType == 'net.daringfireball.markdown' && kMDItemFSContentChangeDate >= \$time.today"

# Files by author
mdfind "kMDItemAuthors == 'Smith'"

# Large files (>100MB)
mdfind "kMDItemFSSize > 100000000"

Date-Based Searches

# Modified in last 7 days
mdfind "kMDItemFSContentChangeDate >= \$time.today(-7)"

# Created this week
mdfind "kMDItemFSCreationDate >= \$time.this_week"

# Modified today
mdfind "kMDItemFSContentChangeDate >= \$time.today"

Name-Based Searches

# Exact filename
mdfind "kMDItemFSName == 'README.md'"

# Filename pattern (case-insensitive)
mdfind "kMDItemFSName == '*.qmd'c"

# Name contains
mdfind "kMDItemDisplayName == '*grant*'c"

Useful Metadata Attributes

Get All Attributes for a File

mdls /path/to/file.pdf

Common Patterns

Find project files

# All files in a project mentioning "EEG"
mdfind -onlyin ~/clawd/Projects "EEG"

Find recent work

# Markdown modified in last 3 days
mdfind "kMDItemContentType == 'net.daringfireball.markdown' && kMDItemFSContentChangeDate >= \$time.today(-3)"

Find by content + type

# Python files containing "import torch"
mdfind "kMDItemFSName == '*.py' && kMDItemTextContent == '*import torch*'"

Count results

mdfind -count "kMDItemContentType == 'com.adobe.pdf'"

Output Options

# Just count
mdfind -count "query"

# Null-separated (for xargs)
mdfind -0 "query" | xargs -0 ls -la

# Pipe to other tools
mdfind -onlyin . "TODO" | head -20

Tips

1. •Use -onlyin to scope searches and speed up results
2. •Wildcards use * and must be quoted: '*pattern*'
3. •Case-insensitive by adding c suffix: '*readme*'c
4. •Combine with grep for content filtering: mdfind "query" | xargs grep -l "specific"
5. •Check indexing status: mdutil -s /

Community Insights

From the original thread:

@udaysy: "been using ripgrep for everything but mdfind would catch stuff outside the project dir too right? like config files scattered across ~/"

Yes! Unlike rg or grep which search from cwd, mdfind searches your entire indexed filesystem by default. Great for finding those scattered config files.

@sentigen_ai: "Also works great paired with fd for when you know the rough name but not the path. mdfind for fuzzy semantic queries, fd for fast exact matches."

Recommended combo:

• •mdfind — fuzzy semantic search (content + metadata)
• •fd — fast exact filename matching
• •rg — fast exact content grep

@sughanthans1: "can it look inside files or just file names"

Both! Spotlight indexes file contents for supported types (PDF, Word, text, code, etc.). Use kMDItemTextContent to explicitly search inside files.

Limitations

• •Only searches Spotlight-indexed locations (not /tmp, external drives unless enabled)
• •Some file types may not have content indexed
• •Check mdutil -s /path to verify indexing status

TL;DR: mdfind "your query" — instant full-text search across your Mac. Add -onlyin ~/folder to scope it. 🔍