macos-service

macOS Service Creator

Create macOS Quick Actions (.workflow bundles) that appear in Finder's right-click > Services menu. These are built programmatically — no Automator GUI needed.

How It Works

A Quick Action is a .workflow bundle installed to ~/Library/Services/. It contains two XML plist files:

<Service Name>.workflow/
  Contents/
    Info.plist          — Controls menu name, accepted file types, which apps show it
    document.wflow      — Automator workflow definition with embedded shell script

Workflow

Step 1: Gather Requirements

Ask the user:

1. What should the service do? — The shell script logic
2. What should it be called? — The name shown in the right-click menu
3. What file types should it accept? — Use UTI types (see below)
4. Should it show feedback? — Dialog box at completion is recommended

Step 2: Write the Shell Script

Write the shell script first as a normal bash script and test it. Selected files are passed as arguments ($@). Key considerations:

• PATH is minimal in Automator — Homebrew tools won't be on PATH. Resolve paths explicitly:

  TOOL=""
  for dir in /opt/homebrew/bin /usr/local/bin /usr/bin; do
      [ -z "$TOOL" ] && [ -x "$dir/toolname" ] && TOOL="$dir/toolname"
  done
  

• Filenames have spaces — Always quote "$f" and "$@"
• Notifications don't work — osascript display notification is silently swallowed by Automator's I/O redirect. Use display dialog instead for user feedback:

  osascript -e 'display dialog "Done!" with title "My Service" buttons {"OK"} default button "OK"'
  

• No interactive input — No stdin, no prompts. Script must run unattended.

Step 3: Build the Workflow Bundle

Create the directory structure and write both plist files. Read references/workflow-template.md for the complete, battle-tested XML templates — use them as-is and only modify the shell script content, service name, and file types.

Info.plist controls:

• NSMenuItem > default — The menu item name
• NSSendFileTypes — Array of UTI strings for accepted file types
• NSRequiredContext > NSApplicationIdentifier — Restrict to Finder with com.apple.finder
• NSMessage — Always runWorkflowAsService

document.wflow contains:

• The Automator action definition wrapping a "Run Shell Script" action
• ActionParameters > COMMAND_STRING — Your shell script (XML-escaped)
• ActionParameters > inputMethod — <integer>1</integer> means "pass input as arguments"
• ActionParameters > shell — /bin/bash
• workflowMetaData — Identifies this as a services menu workflow

Step 4: XML-Escape the Shell Script

The shell script goes inside a <string> element in XML. These characters MUST be escaped:

Character	XML Entity
&	&
<	&lt;
>	&gt;

Common patterns:

• && → &&
• 2>/dev/null → 2>/dev/null
• 2>&1 → 2>&1

Quotes (", ') and $ do NOT need escaping in XML plist <string> elements.

Step 5: Install and Activate

mkdir -p "$HOME/Library/Services/<Service Name>.workflow/Contents"
# Write Info.plist and document.wflow using the Write tool
plutil -lint "$HOME/Library/Services/<Service Name>.workflow/Contents/Info.plist"
plutil -lint "$HOME/Library/Services/<Service Name>.workflow/Contents/document.wflow"
/System/Library/CoreServices/pbs -flush 2>/dev/null

If the service doesn't appear after flushing, the user may need to enable it in System Settings > Keyboard > Keyboard Shortcuts > Services, or restart Finder with killall Finder.

Common UTI Types for NSSendFileTypes

UTI	Matches
public.item	All files and folders
public.data	All files (no folders)
public.movie	All video files
public.audio	All audio files
public.image	All image files
public.mpeg-4	.mp4 files
public.avi	.avi files
org.matroska.mkv	.mkv files
public.plain-text	.txt files
public.json	.json files
com.adobe.pdf	.pdf files
public.folder	Folders only

Resources

references/

• workflow-template.md — Complete XML templates for Info.plist and document.wflow. These are tested, working templates extracted from a real service. Read this file when building the workflow bundle.