“Magic” arguments¶

Customising magic arguments

If your Script Filter (or script) accepts a query (or command line arguments), you can pass it so-called magic arguments that instruct Workflow to perform certain actions, such as opening the log file or clearing the cache/settings.

These can be a big help while developing and debugging and especially when debugging problems your Workflow’s users may be having.

The Workflow.run() method (which you should “wrap” your Workflow’s entry functions in) will catch any raised exceptions, log them and display them in Alfred. You can call your Workflow with workflow:openlog as an Alfred query/command line argument and Workflow will open the Workflow’s log file in the default app (usually Console.app).

This makes it easy for you to get at the log file and data and cache directories (hidden away in ~/Library), and for your users to send you their logs for debugging.

Note

Magic arguments will only work with scripts that accept arguments and use the args property (where magic arguments are parsed).

Workflow supports the following magic arguments by default:

workflow:magic — List available magic arguments.
workflow:help — Open workflow’s help URL in default web browser. This URL is specified in the help_url argument to Workflow.
workflow:version — Display the installed version of the workflow (if one is set).
workflow:delcache — Delete the Workflow’s cache.
workflow:deldata — Delete the Workflow’s saved data.
workflow:delsettings — Delete the Workflow’s settings file (which contains the data stored using Workflow.settings).
workflow:foldingdefault — Reset diacritic folding to workflow default
workflow:foldingoff — Never fold diacritics in search keys
workflow:foldingon — Force diacritic folding in search keys (e.g. convert ü to ue)
workflow:opencache — Open the Workflow’s cache directory.
workflow:opendata — Open the Workflow’s data directory.
workflow:openlog — Open the Workflow’s log file in the default app.
workflow:openterm — Open a Terminal window in the Workflow’s root directory.
workflow:openworkflow — Open the Workflow’s root directory (where info.plist is).
workflow:reset — Delete the Workflow’s settings, cache and saved data.
workflow:update — Check for a newer version of the workflow using GitHub releases and install the newer version if one is available.
workflow:noautoupdate — Turn off automatic checks for updates.
workflow:autoupdate — Turn automatic checks for updates on.
workflow:prereleases — Enable updating the workflow to pre-release versions.
workflow:noprereleases — Disable updating the workflow to pre-release versions (default).

The three workflow:folding… settings allow users to override the diacritic folding set by a workflow’s author. This may be useful if the author’s choice does not correspond with a user’s usage pattern.

You can turn off magic arguments by passing capture_args=False to Workflow on instantiation, or call the corresponding methods of Workflow directly, perhaps assigning your own keywords within your Workflow:

open_help()
open_log()
open_cachedir()
open_datadir()
open_workflowdir()
open_terminal()
clear_cache()
clear_data()
clear_settings()
reset() (a shortcut to call the three previous clear_* methods)
check_update()
start_update()

Customising magic arguments ¶

The default prefix for magic arguments (workflow:) is contained in the magic_prefix attribute of Workflow. If you want to change it to, say, wf: (which will become the default in v2 of Alfred-Workflow), simply reassign it:

wf.magic_prefix = 'wf:'

The magic arguments are defined in the Workflow.magic_arguments dictionary. The dictionary keys are the keywords for the arguments (without the prefix) and the values are functions that should be called when the magic argument is entered. You can show a message in Alfred by returning a unicode string from the function.

To add a new magic argument that opens the workflow’s settings file, you could do:

wf = Workflow()
wf.magic_prefix = 'wf:'  # Change prefix to `wf:`

def opensettings():
        subprocess.call(['open', wf.settings_path])
        return 'Opening workflow settings...'

wf.magic_arguments['settings'] = opensettings