mac-spotlight
Find files on a Mac the way Spotlight does, from the shell — by kind, date, content, name or Finder tag — and read or write Finder tags. Use when you say "find all PDFs I touched this week", "search m
SKILL.mdskills/mac-spotlight/SKILL.md
GitHubSpotlight from the shell
mdfind is a query against the Spotlight index, not a walk of the disk. That makes it
instant on a million files, and it means an empty result proves nothing until you have
ruled out the four traps at the bottom. When the answer has to be exhaustive, fall back to
find.
Queries that work
Always scope with -onlyin (faster, and keeps the result off system caches). Pipe stderr
to /dev/null: on macOS 26 every mdfind call prints two [UserQueryParser] Loading keywords... lines to stderr even on success.
mdfind -onlyin ~/Documents "quarterly report" 2>/dev/null # full-text + metadata
mdfind -onlyin ~/Documents -name invoice 2>/dev/null # filename substring
mdfind -onlyin ~ -count 'kMDItemContentTypeTree == "com.adobe.pdf"' 2>/dev/null
mdfind -onlyin ~ 'kind:pdf' 2>/dev/null # same result, natural syntax
mdfind -onlyin ~/Desktop 'kMDItemFSContentChangeDate >= $time.today(-7) && kMDItemContentTypeTree == "public.image"' 2>/dev/null
mdfind -onlyin ~ 'kMDItemUserTags == "Red"' 2>/dev/null # by Finder tag
mdfind -onlyin ~ 'tag:Red' 2>/dev/null # same, natural syntax
mdfind -onlyin ~/Downloads 'kMDItemWhereFroms == "*github.com*"c' 2>/dev/null # downloaded from
mdfind -onlyin ~ 'kMDItemFSSize > 500000000' 2>/dev/null # files over 500 MB
- Use
kMDItemContentTypeTree, notkMDItemContentType, for kinds: the tree matches parents, sopublic.imagecatches PNG, JPEG and HEIC, andpublic.moviecatches every video. - Single-quote the whole query so the shell leaves
$timeand*alone. - Suffix modifiers on a string:
ccase-insensitive,ddiacritic-insensitive,wword. - Time functions:
$time.today(-7),$time.this_month,$time.iso(2026-01-01T00:00:00Z). mdfind -live ...keeps running and prints changes; useful in a watcher, never in a one-shot.
What a file actually carries
mdls file.pdf # every attribute
mdls -name kMDItemContentType -name kMDItemKind -name kMDItemFSSize file.pdf
mdls -raw -name kMDItemWhereFroms file.zip # download URL; prints (null) if none
mdls is how you discover the attribute name for a query: inspect a file that should
match, copy the key.
Finder tags — read and write without a third-party tool
Tags live in the extended attribute com.apple.metadata:_kMDItemUserTags as a plist array.
A colour tag is "Name\nN" (newline, then the colour index: 1 grey, 2 green, 3 purple,
4 blue, 5 yellow, 6 red, 7 orange). A plain label has no suffix.
# read
xattr -p com.apple.metadata:_kMDItemUserTags file.txt | plutil -p -
# write (REPLACES all tags on the file)
xattr -w com.apple.metadata:_kMDItemUserTags '<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><array><string>Red
6</string><string>project-x</string></array></plist>' file.txt
mdimport file.txt # push the change into the index now
mdls -name kMDItemUserTags file.txt
- Writing replaces. To add a tag, read the array, append, write the whole array back.
cpkeeps the tags (it copies xattrs).cat a > band most uploads drop them.- If
brew install tagis acceptable,tag -a Red file/tag -lis friendlier; the xattr route needs nothing installed.
Index status and repair
mdutil -s / # "Indexing enabled." is what you want
mdutil -s /path/to/volume # external disks are often off
mdimport /path/to/file # re-index one file immediately (no sudo)
sudo mdutil -E / erases and rebuilds the whole index (hours, high CPU). It needs a
human with an admin password and it is almost never the fix. Reach for it only when a
whole volume returns nothing.
The four ways mdfind returns nothing and lies about it
- The path is not indexed.
/tmp,/private/tmp, scratch dirs, many external volumes and anything under a folder ending.noindexare never indexed. Tell:mdutil -s <path>printsError: unknown indexing state.orIndexing disabled. Verified: a file in/private/tmpwith unique text returned 0 hits forever. - The file is too new. Indexing lags. Measured: a new file under
~took ~6 s to appear. In a script,mdimportthe file first or poll for a few seconds. - Privacy exclusions. System Settings > Spotlight > Search Privacy hides folders
from
mdfindwith no message. Ask, or check withfind. - Your process lacks access. Results inside TCC-protected folders (Desktop,
Documents, Downloads, Mail, Messages) only come back if the calling app has the grant.
See the
mac-permissionsskill.
When an exhaustive answer matters (a deletion, an audit), confirm with
find <dir> -iname '*term*' or grep -rl. Spotlight is for speed, not for proof.