Links and scripts

Links

The last part is the action's ID or its name. IDs don't change when you rename an action, so links copied from Action Hero use them. A name works too, with spaces written as %20: actionhero://run/Say%20Hello. Names are matched without regard to case.

actionhero://run/turntable_stream?state=on means the same as actionhero://on/turntable_stream (?state=off too), for tools that build links that way.

Readouts show a value and don't run anything, so they have no links. Read their values from the file below.

Getting an action's link

In Action Hero, choose Edit Actions…. Each action's ⋯ menu has Copy Link: for a switch, pick Turn On, Turn Off or Flip; for a button, Run.

Which apps can run your actions

Any app can open a link, and so can a web page if your browser lets it. So the first link from each app asks before it runs anything:

Let Alfred run your actions? Alfred opened a link to run “Say Hello” on studio.

If you allow it, that app runs links straight away from then on. If you don't, its links are turned away, with a notification saying so. Action Hero → Settings → General → Links lists the apps you've answered for; Forget makes an app ask again.

• A script that runs open actionhero://… counts as the app that ran the script: an Alfred workflow's script is Alfred, a command you type in Terminal is Terminal.
• When macOS doesn't say where a link came from, Action Hero asks every time, with Run and Don't Run.
• A link from a web page comes from your browser, so a web page can only run your actions if you've allowed that browser. Most browsers also ask before a page opens a link to an app.

What happens when a link runs

A link that works does its job quietly: no window, no sound. Watch the action's state in Action Hero's menu, or in the file below.

When a link can't run, a notification says why (allow notifications for Action Hero the first time it asks; with them off, it beeps):

• your host can't be reached: asleep, turned off, or on another network
• the host has no action with that ID or name
• the link tries to turn a button on or off, or to run a readout
• the action ran but failed, with what it reported
• links from that app are turned off

If your host isn't connected when a link arrives, Action Hero waits up to 10 seconds for it.

Reading your actions

Action Hero keeps this file up to date with your host's actions, their state and their links:

~/Library/Application Support/ActionHero/remote-actions.json

{
  "host" : "studio",
  "connected" : true,
  "updated" : "2026-10-29T00:43:26Z",
  "actions" : [
    {
      "id" : "turntable_stream",
      "title" : "Turntable Stream",
      "kind" : "switch",
      "icon" : "record.circle",
      "on" : false,
      "value" : "stopped",
      "links" : {
        "on" : "actionhero://on/turntable_stream",
        "off" : "actionhero://off/turntable_stream",
        "flip" : "actionhero://run/turntable_stream"
      }
    },
    {
      "id" : "say_hello",
      "title" : "Say Hello",
      "kind" : "button",
      "icon" : "speaker.wave.2",
      "links" : { "run" : "actionhero://run/say_hello" }
    },
    {
      "id" : "uptime",
      "title" : "Uptime",
      "kind" : "readout",
      "icon" : "clock",
      "value" : "16 days, 3:12",
      "links" : { }
    }
  ]
}

Action Hero rewrites the file within a second of anything changing. When the host goes away it keeps the last actions it saw, with connected set to false and no states. The file is only for reading: change your actions in Action Hero.

Recipes

Alfred

The Action Hero workflow lists your actions as you type ah:

• ↩ flips a switch (to the opposite of what it shows) or runs a button
• ⌘↩ turns a switch on, ⌥↩ turns it off
• a readout shows its value, and ⌘C copies it

Download the Alfred workflow

Double-click it to add it to Alfred (Alfred 5 with the Powerpack). The first time you run an action, Action Hero asks whether Alfred may run your actions.

One action on a hotkey: in Alfred's Workflows, add a Hotkey trigger and connect it to an Open URL action whose URL is the action's link.

Your own keyword: a Keyword input connected to Open URL, the same way.

Raycast

Quicklinks: run Create Quicklink, give it a name (“Start Turntable Stream”) and paste the link. It then shows up when you search Raycast.

Script commands, to use the state as well. This one turns a switch on or off depending on how it is now:

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Turntable Stream
# @raycast.mode silent

file="$HOME/Library/Application Support/ActionHero/remote-actions.json"
on=$(jq -r '.actions[] | select(.id == "turntable_stream") | .on' "$file")
if [ "$on" = "true" ]; then
  open "actionhero://off/turntable_stream"
else
  open "actionhero://on/turntable_stream"
fi

actionhero://run/turntable_stream flips it in one go; the script is a starting point for doing more with the state. jq comes with macOS 15 and later.

Stream Deck

Add a Website action (under System) and set its URL to the link. Stream Deck hands links that aren't web addresses to macOS, which opens them in Action Hero.

Keyboard Maestro

Use the Open URL action with the link. Any trigger works: a hotkey, a USB device, a time of day.

BetterTouchTool

Assign the Open URL action to a gesture, key or Touch Bar button, with the link as the URL.

Shell and AppleScript

open "actionhero://on/turntable_stream"

open location "actionhero://run/say_hello"

To read a value in a script (jq comes with macOS 15 and later):

jq -r '.actions[] | select(.id == "uptime") | .value' \
  "$HOME/Library/Application Support/ActionHero/remote-actions.json"

Shortcuts

Shortcuts has its own Action Hero actions (Turn On Action, Turn Off Action, Run Action, Is Action On, Get Action Value). They're easier than links there, and they say whether the action worked.

Limits

• Links run on the host the Mac is connected to. If you have more than one host, they go to the one Action Hero's menu shows.
• Links only run actions that exist. They can't add, change or remove actions.
• Links are a Mac feature. On iPhone and iPad, use the Shortcuts actions.