Spotlight Search

Overview

Use mdfind first for indexed search, mdls for metadata inspection, and mdutil only when diagnosing indexing issues. If Spotlight misses a known file, use the bundled fallback script instead of hand-rolling a find command every time.

Quick Start

Preferred flow:

1. 1. Use mdfind for normal search.
2. Use mdls when the task is about metadata, not discovery.
3. Use ./scripts/spotlight_search.sh when Spotlight indexing is incomplete or results are unexpectedly empty.
4. Treat the fallback script as a filename/path matcher, not a general shell helper.
5. Use mdutil only to inspect indexing, and only suggest re-indexing when the user explicitly wants that system-level change.

CODEBLOCK0

For a hybrid search that tries Spotlight first and falls back to find, use the bundled script:

CODEBLOCK1

Core Capabilities

1. File Search

Spotlight indexes file contents and metadata, making it ideal for locating documents when you remember words inside them.

Common patterns:

• - Simple keyword: INLINECODE9
• By file type: INLINECODE10
• By extension: INLINECODE11
• By date: INLINECODE12
• By size: mdfind 'kMDItemFSSize > 1000000' (files >1 MB)

When to use: You recall words from the file's content, need to filter by type/date, or want to search across all indexed volumes quickly.

2. Application Search

Spotlight knows about installed applications (.app bundles) and can find them by name or bundle identifier.

Examples:

CODEBLOCK2

When to use: You need to locate an installed app, verify its presence, or get its bundle path.

3. Metadata Inspection

Use mdls to view the rich metadata Spotlight stores for any file.

CODEBLOCK3

Common attributes: kMDItemKind, kMDItemContentType, kMDItemAuthors, kMDItemContentCreationDate, kMDItemPixelHeight, kMDItemDurationSeconds.

When to use: You need to check file properties (creation date, dimensions, author) without opening the file.

4. Hybrid Search (Fallback)

Spotlight indexing may be incomplete (excluded directories, recent files not yet indexed). The bundled script scripts/spotlight_search.sh provides a hybrid approach:

1. 1. Attempts Spotlight search via INLINECODE23
2. If no results, falls back to find with name‑based matching
3. Uses shell argument arrays instead of eval, so the query is passed as data rather than executable shell text
4. Supports filtering by kind (pdf, image, application, etc.)

Usage:

CODEBLOCK4

When to use: You want maximum recall, or Spotlight is returning empty results for known files.

Reference Materials

For detailed query syntax, operator reference, and advanced examples, see:

• - mdfind Query Reference – Comprehensive guide to mdfind syntax, attribute filters, date comparisons, and practical examples.

Load this reference when you need to construct complex queries or understand Spotlight's capabilities.

Workflow Guidance

Choosing the Right Tool

Troubleshooting

No results for known files?

1. 1. Check indexing status: INLINECODE36
2. Ensure the directory is indexed (Spotlight excludes some system and Library folders)
3. Re-index only with explicit user approval because it is a privileged, system-wide action: INLINECODE37

Query syntax errors?

• - Enclose queries containing spaces or special characters in single quotes.
• Use cd after == for case‑ and diacritic‑insensitive matching: INLINECODE40
• Combine filters with AND/OR and parentheses.

Slow performance?

• - Limit results with INLINECODE43
• Restrict search scope with INLINECODE44

Notes

• - Spotlight indexing is not real‑time; newly created files may take minutes to appear.
• Some directories (e.g., ~/Library, system folders) may be excluded from indexing.
• INLINECODE46 searches all indexed volumes by default; use -onlyin to constrain.
• The hybrid script requires find (always present) and optionally fd (faster).

See Also

• - INLINECODE50
• INLINECODE51
• INLINECODE52
• Apple's Uniform Type Identifier reference: https://developer.apple.com/documentation/uniformtypeidentifiers