Namespace 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()
Copy

One-shot search convenience

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

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()
Copy

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
Copy