API Reference

Looking for a step-by-step guide to creating plugins? Look here.

Supported info.json Keys

• name This must be the same as the name of your plugin bundle (minus the .bundle extension)
• displayName
• description
• examples (array of strings)
• categories (array of categories. See the app for category names. Category names should have their first-letter capitalized, exactly how they appear in the English version of the app.)
• description_fr, displayName_zh, examples_de, etc — append country codes to keys (in addition to their english versions, which should not have en appended). See Internationalization

plugin.py Interface

Method: results(parsed, original_query)

parsed: {String: String} dictionary mapping tagged sections of the query (extracted using the examples in examples.txt), to the text they contain.

original_query: string

Return value: A json dictionary containing any of the following keys:

• title: result title in Spotlight
• html: html to show inline in Spotlight
• run_args: arguments to be passed to the run() function (described below) if your result is clicked or enter is pressed. Must be JSON-serializable.
• webview_links_open_in_browser: clicking links in Spotlight opens the browser
• dont_force_top_hit: don't force this result to be to #1 hit in Spotlight
• webview_user_agent: custom user agent for the webview (useful for forcing a mobile view of a site)
• webview_transparent_background: give the webview a transparent background. You'll probably want to use the dark_mode module to detect Yosemite dark mode and adjust your CSS.
• pass_result_of_output_function_as_first_run_arg: calls any function in your webview's Javascript named output(), and passes the resulting JSON-serializable object as the first argument to your run() function

Method: run(...)

Called with all arguments from run_args. This process has about ~20 seconds to run before being killed; spawn a new process for long-running work.

Javascript API

When you return HTML and Javascript from your results function, it has available to it a special Javascript object called flashlight. It's got a single method: bash(script): executes a string as a bash script, and returns the stdout result to Javascript. Only available for local HTML, not remote sites. Note: in your local HTML, you can make cross-site AJAX requests. This is, again not available to remote pages running inside Spotlight.

Settings API

Your plugin can show a settings screen for infrequently-changed settings and configuration. See the Settings API docs