mdfind

name	mdfind
description	Search your entire Mac instantly using Spotlight's CLI. No RAG, no indexing setup, works out of the box.
homepage	https://x.com/_chenglou/status/2018915948456214940
metadata	{"openclaw":{"emoji":"🔍","requires":{"bins":["mdfind"]},"platforms":["darwin"]}}

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

Attribute	Description
kMDItemFSName	File name
kMDItemDisplayName	Display name
kMDItemTextContent	File contents
kMDItemContentType	UTI type
kMDItemFSSize	File size (bytes)
kMDItemFSCreationDate	Created date
kMDItemFSContentChangeDate	Modified date
kMDItemAuthors	Authors
kMDItemTitle	Document title
kMDItemKeywords	Keywords/tags

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. 🔍