hs.spotlight

Query the macOS Spotlight metadata database.

hs.spotlight wraps NSMetadataQuery to let you search for files and other metadata objects indexed by Spotlight. Queries use NSPredicate syntax with kMDItem* attribute keys (see hs.spotlight.attribute for common shortcuts).

Quick start

// Find all PDFs in the home directory and log their paths
const q = hs.spotlight.create()
q.setQuery("kMDItemContentType == 'com.adobe.pdf'")
 .setScopes([hs.spotlight.scope.home])
 .setCallback((event) => {
     if (event === 'didFinish') {
         console.log('Found ' + q.count + ' PDFs')
         q.results().forEach(item =>
             console.log(item.valueForAttribute(hs.spotlight.attribute.path))
         )
         q.stop()
     }
 })
 .start()

One-shot search convenience

const q = hs.spotlight.search(
    "kMDItemDisplayName BEGINSWITH 'Invoice'",
    (event) => {
        if (event === 'didFinish') {
            console.log('Found ' + q.count + ' invoices')
            q.stop()
        }
    }
)

Grouping results by attribute

const q = hs.spotlight.create()
q.setQuery("kMDItemContentTypeTree == 'public.image'")
 .setScopes([hs.spotlight.scope.home])
 .setGroupingAttributes([hs.spotlight.attribute.kind])
 .setCallback((event) => {
     if (event === 'didFinish') {
         q.groups().forEach(g =>
             console.log(g.value() + ': ' + g.count + ' images')
         )
         q.stop()
     }
 })
 .start()

Monitoring for live changes

// Keep the query running to receive live-update events
const q = hs.spotlight.create()
q.setQuery("kMDItemContentType == 'com.apple.application-bundle'")
 .setScopes(['/Applications'])
 .setCallback((event, update) => {
     if (event === 'didFinish') {
         console.log('Initial scan: ' + q.count + ' apps')
     } else if (event === 'didUpdate') {
         console.log('App list changed — now ' + q.count + ' apps')
         if (update) console.log('Added: ' + update.added.length)
     }
 })
 .start()
// Call q.stop() when you no longer want live updates