DeckPilot
All troubleshooting

AppleScript: Common Issues & Best Practices

How to write AppleScript button actions that work reliably when DeckPilot runs them.

My dialog or picker doesn't show up

The most common surprise — and it's not a DeckPilot bug.

DeckPilot lives in your menu bar (it's a background / accessory app, with no Dock icon). When it runs your script, commands like display dialog, display alert, and choose … belong to DeckPilot's own process. macOS will not bring a background app's window to the front on its own, so the dialog only appears when DeckPilot happens to be the active app. This is how macOS handles background apps — every menu-bar utility hits it.

The fix (recommended): show the dialog through System Events. It comes straight to the front in any app, and macOS asks for permission once (“DeckPilot wants to control System Events”) instead of once per app.

Before — may stay hidden behind your work

display dialog "Hello" buttons {"OK"} default button 1

After — always pops to the front (one permission)

tell application "System Events"
    display dialog "Hello" buttons {"OK"} default button 1
end tell

Wrap every display dialog / display alert / choose … the same way. To read the button back:

set answer to button returned of (tell application "System Events" to ¬
    display dialog "Refresh?" buttons {"Cancel", "Refresh"} default button 2)

Alternative: target the frontmost app with tell application (path to frontmost application as text). It also works, but macOS asks permission the first time for each app you run it in — System Events is the smoother default.

Just showing info? Prefer a notification

If you only need to tell the user something (no buttons), use a notification — it never has the front-most problem and doesn't interrupt:

display notification "BTC $64,000" with title "Bitcoin" subtitle "+2.4% today"

Running shell commands (do shell script)

do shell script (curl, python3, awk, etc.) works in DeckPilot 1.3.2 and later. On older builds it was blocked — update via DeckPilot › Check for Updates if your script reports “Shell script execution is not permitted.”

  • Use full paths or rely on the default PATH; GUI apps get a minimal environment.
  • Quote arguments with quoted form of to avoid breakage on spaces.
  • Force a dot decimal separator in scripts that parse numbers (e.g. en_US.UTF-8 locale) so Italian/EU systems don't choke.

Permissions

The first time a script controls another app you'll see a macOS prompt. If a script fails with “not authorized to send Apple events” or nothing happens, grant access here:

  • System Settings › Privacy & Security › Automation — allow DeckPilot to control the apps your script targets.
  • Accessibility — required if you send keystrokes or move/close windows.
  • Use the Test button in DeckPilot's script editor to trigger the prompts and confirm it runs before you save.

Best practices

  • Target the frontmost app for any dialog, alert, or chooser.
  • Always Test in the editor — it runs the exact same way DeckPilot will.
  • Keep scripts fast. Long-running work blocks the button; DeckPilot stops a script after 30s.
  • Reference apps by name in a tell block, and make sure the app is installed.
  • For info you check often, prefer a notification over a modal dialog.
  • Clean up any temp files your script creates.

Common errors

Dialog never appears

Wrap it in tell application (path to frontmost application as text).

“Shell script execution is not permitted”

Update to DeckPilot 1.3.2+ (do shell script is allowed there).

“Not authorized to send Apple events”

Allow DeckPilot in System Settings › Privacy & Security › Automation.

Numbers parse wrong / “can’t make … into number”

Force a dot decimal (en_US locale) and convert text to number explicitly.

“Script timed out after 30s”

Shorten the work or move slow network/processing out of the button action.

Still stuck? See connection troubleshooting or contact support.