Scripting Actions

Table of contents

  1. Apps
    1. App ID Shorthands
    2. Hide App
    3. Hide All Apps
    4. Open App
    5. Quit App
    6. Quit All Apps
    7. Kill App
    8. Kill All Apps
    9. Split Screen Apps
      1. Ratios
    10. Get Apps
  2. Content
    1. Get On-Screen Content
  3. Control Flow
    1. Output
    2. Must Output
    3. Output or Clipboard
    4. Wait
    5. Wait to Return
  4. Device
    1. Get Battery Level
    2. Battery Is Charging
    3. Connected to Charger
    4. Turn On Do Not Disturb
    5. Turn Off Do Not Disturb
    6. Get Device Detail
      1. Device Details
    7. Lock Screen
    8. Log Out User
    9. Put Display to Sleep
    10. Toggle Appearance
    11. Light Appearance
    12. Dark Appearance
    13. Toggle Bluetooth
    14. Set Bluetooth
    15. Set Brightness
    16. Set Night Shift
    17. Toggle Night Shift
    18. Set True Tone
    19. Toggle True Tone
    20. Set Volume
    21. Shut Down
    22. Restart
    23. Sleep
    24. Start Screensaver
  5. Dictionaries
    1. Get Dictionary
    2. Get Values from Dictionary
    3. Get Keys from Dictionary
    4. Get Value from Dictionary
    5. Set Value in Dictionary
  6. Files
    1. Base 64 Encode
    2. Base 64 Decode
    3. Hash
      1. Hash Types
  7. Items
    1. Count Items
    2. Count Characters
    3. Count Words
    4. Count Sentences
    5. Count Lines
    6. Get Name
    7. Get Type
    8. Set Name
    9. Content Graph
  8. Lists
    1. Choose from List
    2. Get First Item
    3. Get Last Item
    4. Get Random Item
    5. Get Item at Index
    6. Get List Items in Range
    7. List
  9. Math
    1. Calculate
      1. Calculation Operations
    2. Calculate Expression
    3. Calculate Statistics
      1. Statistics Operations
    4. Rounding
      1. Shorthands for roundTo:
  10. Measurements
    1. Measurement
      1. Measurement Types & Units
    2. Convert Measurement
  11. Network
    1. Is Online
    2. Get Local IP
      1. IP Types
    3. Get External IP
    4. Set Cellular Data
    5. Set Cellular Voice
    6. Set WiFi
  12. No-ops (noonce)
    1. Comments
    2. Nothing
  13. Notification
    1. Ask for Input
      1. Input Types
    2. Play Sound
    3. Alert
    4. Confirm
    5. Show Notification
  14. Numbers
    1. Number
    2. Format File Size
      1. File Size Format Units
    3. Format Number
    4. Get Numbers
    5. Random Number
  15. Shell
    1. Run Shell Script
      1. Input Modes
  16. Script Editor
    1. Run AppleScript
    2. Run JavaScript for Mac Automation
  17. Shortcuts
    1. Get Shortcuts
    2. Create Shortcut
    3. Search Shortcuts
    4. Get Shortcut Detail
      1. Details
    5. Open Shortcut
    6. Run Shortcut
    7. Run Self
    8. Stop Shortcut
  18. System
    1. Dismiss Siri
    2. Set Wallpaper
    3. Get Wallpaper
  19. Variables
  20. Windows
    1. Find Windows
    2. Sort By
      1. Order By
    3. Move Windows
      1. Window Positions
    4. Resize Windows
      1. Window Configurations
  21. X-Callback
    1. Open X-Callback URL
    2. Open Custom X-Callback URL

Apps

App ID Shorthands

Shorthands are built into any of the following actions accepting App IDs. However, if you use these values they must be available at compile time.

  • appstore
  • files
  • shortcuts
  • safari
  • facetime
  • notes
  • phone
  • reminders
  • mail
  • music
  • calendar
  • maps
  • contacts
  • health
  • photos

Hide App

Hide app with appId.

hideApp(text appId)

Hide All Apps

Hide all open apps.

hideAllApps(text ...?except)

Open App

Open app with appId.

openApp(text appId)

Contributed by JosephShenton.

Quit App

Quit app with appId.

quitApp(text appId)

Quit All Apps

Quit all open apps, asking to save changes.

quitAllApps(text ...?except)

Kill App

Quit an app with appId without asking to save changes.

killApp(text appId)

Kill All Apps

This will quit all of the apps on the device without asking to save changes!

Quit all open apps, without asking to save changes.

killAllApps(text ...?except)

Split Screen Apps

Split two apps on the device screen.

splitApps(text firstAppID, text secondAppID, enum ?ratio = "half")

Ratios

  • half
  • thirdByTwo

Get Apps

Gets all of the apps on the device.

getApps()

Note: iOS 18+, macOS only

Content

Get On-Screen Content

Get content on the device screen.

getOnScreenContent()

Control Flow

These control flow actions have been abstracted into statements: Choose From Menu, If, Repeat and Repeat With Each.

Output

Stop and output output. Do nothing if there is nowhere to output.

output(text output)

Must Output

Stop and output output. Respond with response if there is nowhere to output.

mustOutput(text output, text response)

Output or Clipboard

Stop and output output. Copy to the clipboard if there is nowhere to output.

outputOrClipboard(variable output)

Wait

Wait a number of seconds then proceed.

wait(integer seconds)

Wait to Return

Wait for the user to return to the Shortcut. This usually proceeds an action that directs the user out of the Shortcuts app.

waitToReturn()

Device

Get Battery Level

Get the current battery level of the device.

getBatteryLevel()

Battery Is Charging

Returns a boolean based on if the device is charging.

isCharging()

iOS 16.2+ only

Connected to Charger

Returns a boolean based on if the device is connected to a charger.

connectedToCharger()

iOS 16.2+ only

Turn On Do Not Disturb

Turn on the Do Not Disturb focus mode on the device.

DNDOn()

Turn Off Do Not Disturb

Turn off the Do Not Disturb focus mode on the device.

DNDOff()

Get Device Detail

Get detail of the device.

getDeviceDetail(enum detail)

Device Details

  • Device Name
  • Device Hostname
  • Device Model
  • Device Is Watch
  • System Version
  • Screen Width
  • Screen Height
  • Current Volume
  • Current Brightness
  • Current Appearance

Lock Screen

Lock the device’s screen.

lockScreen()

Log Out User

Logout the current user.

logout()

macOS only

Put Display to Sleep

Put the display to sleep.

displaySleep()

macOS only

Toggle Appearance

Toggles system appearance from light to dark, or dark to light.

toggleAppearance()

Light Appearance

Change system appearance to light.

lightMode()

Dark Appearance

Change system appearance to dark.

darkMode()

Toggle Bluetooth

Toggle device Bluetooth.

toggleBluetooth()

Set Bluetooth

Set the device Bluetooth on or off.

setBluetooth(boolean status)

Set Brightness

This feature is in an upcoming release.

Set display brightness (0.0 - 1.0).

setBrightness(float brightness)

Set Night Shift

This feature is in an upcoming release.

Set status of Night Shift.

setNightShift(bool status)

Toggle Night Shift

This feature is in an upcoming release.

Toggle Night Shift.

toggleNightShift()

Set True Tone

This feature is in an upcoming release.

Set status of True Tone.

setTrueTone(bool status)

Toggle True Tone

This feature is in an upcoming release.

Toggle True Tone.

toggleTrueTone()

Set Volume

This feature is in an upcoming release.

Set device volume (0.0 - 1.0).

setVolume(float volume)

Shut Down

Shut down the device.

shutdown()

Restart

Restart the device.

reboot()

Sleep

Set the device to enter sleep mode.

sleep()

macOS only

Start Screensaver

Start screen saver on Mac.

startScreensaver()

macOS only

Dictionaries

The dictionary action is abstracted into a variable value, see Dictionary.

Get Dictionary

Get the dictionary from input.

getDictionary(variable input)

Get Values from Dictionary

Get only the values from the dictionary.

getValues(dictionary dictionary)

Get Keys from Dictionary

Get only the keys from the dictionary.

getKeys(dictionary dictionary)

Get Value from Dictionary

Get the value of key in dictionary.

getValue(dictionary dictionary, text key)

// or raw string get as... but no variable references are allowed.
dictionary['key']

Set Value in Dictionary

Set the value of key to value in dictionary.

setValue(variable dictionary, text key, variable value)

Files

Base 64 Encode

Base 64 encodes input.

base64Encode(variable encodeInput)

Base 64 Decode

Base 64 decodes input.

base64Decode(variable input)

Hash

Generate a hash of type using input.

hash(variable input, enum ?type = "MD5")

Hash Types

  • MD5
  • SHA1
  • SHA256
  • SHA512

Items

Count Items

Returns the number of items in input.

count(variable input)

Count Characters

Returns the number of characters in input.

countChars(variable input)

Count Words

Returns the number of words in input.

countWords(variable input)

Count Sentences

Returns the number of sentences in input.

countSentences(variable input)

Count Lines

Returns the number of lines in input.

countLines(variable input)

Get Name

Get the name of input.

getName(variable item)

Get Type

Get the type of input.

typeOf(variable input)

Set Name

Set the name of item.

setName(variable item, text name, boolean ?includeFileExtension = false)

Content Graph

Show input as a graph.

contentGraph(variable input)

Lists

Choose from List

Prompt the user to choose an item from list, optionally with prompt . Returns the item(s) chosen.

chooseFromList(variable list, text ?prompt, bool ?selectMultiple = false, bool ?selectAll = false)

Get First Item

Get the first item from the list.

getFirstItem(variable list)

Get Last Item

Get the last item from the list.

getLastItem(variable list)

Get Random Item

Get a random item from the list.

getRandomItem(variable list)

Get Item at Index

Get the item at index from list. Counting in Shortcuts starts at 1.

getListItem(variable list, integer index)

Shortcuts start counting indexes at 1.

Get List Items in Range

Get items in the list within the range of start to end.

getListItems(variable list, integer start, integer end)

Shortcuts start counting indexes at 1.

List

Create a list of items. The listItem argument has no limit.

list(text ...listItem)

Math

Calculate

Perform a complex calculation.

calculate(enum operation, integer operandOne, integer ?operandTwo)

The operandTwo is optional as not all of the operations require a second operand.

Calculation Operations

  • x^2
  • х^3
  • x^у
  • e^x
  • 10^x
  • In(x)
  • log(x)
  • √x
  • ∛x
  • x!
  • sin(x)
  • cos(X)
  • tan(x)
  • abs(x)

Calculate Expression

To do this, create a variable and set a basic mathematical expression (+,-,*,/,%) as the value.

@expression = 25 * 6 + (5 / 6) % 2

Calculate Statistics

Calculate the statistic of operation on input.

statistic(enum operation, variable input)

Statistics Operations

  • Average
  • Minimum
  • Maximum
  • Sum
  • Median
  • Mode
  • Range
  • Standard Deviation

Rounding

Round number to roundTo.

Normal

round(integer number, text roundTo)

Always Round Up

ceil(integer number, text roundTo)

Always Round Down

floor(integer number, text roundTo)

Shorthands for roundTo:

  • 1 - Ones Place
  • 10 - Tens Place
  • 100 - Hundreds Place
  • 1000 - Thousands
  • 10000 - Ten Thousands
  • 100000 - Hundred Thousands
  • 1000000 - Millions

Measurements

Measurement

Create a measurement.

measurement(text magnitude, enum unitType, text unit)

Example:

measurement("2000","Information Storage","MB")

Measurement Types & Units

  • Acceleration
    • m/s²
    • g-force
  • Angle
    • degrees
    • arcminutes
    • arcseconds
    • radians
    • grad
    • revolutions
  • Area
    • Mm²
    • square kilometers
    • square meters
    • square centimeters
    • mm²
    • um²
    • nm²
    • square inches
    • square feet
    • square yards
    • square miles
    • acres
    • a
    • hectares
  • Concentration Mass
    • g/L
    • mg/dL
    • µg/m³
  • Dispersion
    • ppm
  • Duration
    • milliseconds
    • microseconds
    • nanoseconds
    • ps
    • seconds
    • minutes
    • hours
  • Electric Charge
    • C
    • MAh
    • kAh
    • Ah
    • mAh
    • µAh
  • Electric Current
    • MA
    • kA
    • amp
    • mA
    • µA
  • Electric Potential Difference
    • MV
    • kV
    • volt
    • mV
    • µV
  • Electric Resistance
    • MΩ
    • kΩ
    • ohm
    • mΩ
    • µΩ
  • Energy
    • kJ
    • joule
    • kcal
    • cal
    • kWh
  • Frequency
    • tHz
    • GHz
    • MHz
    • kHz
    • Hz
    • mHz
    • µHz
    • nHz
    • fps
  • Fuel Efficiency
    • L/100km
    • mpg
  • Illuminance
    • lux
  • Information Storage
    • B
    • KB
    • MB
    • GB
    • TB
    • PB
    • EB
    • ZB
    • YB
  • Length
    • Mm
    • km
    • hm
    • dam
    • m
    • dm
    • cm
    • mm
    • µm
    • nm
    • pm
    • in
    • ft
    • yd
    • mi
    • smi
    • ly
    • nmi
    • fathom
    • furlong
    • au
    • parsec
  • Mass
    • kg
    • gram
    • dg
    • cg
    • mg
    • µg
    • ng
    • pg
    • oz
    • lb
    • stone
    • t
    • ton
    • carat
    • oz t
    • slug
  • Power
    • TW
    • GW
    • MW
    • kW
    • watt
    • mW
    • µW
    • nW
    • pW
    • fW
    • hp
  • Pressure
    • N/m²
    • GPa
    • MPa
    • kPa
    • hPa
    • ” Hg
    • bar
    • mbar
    • mm Hg
    • psi
  • Speed
    • m/s
    • km/hr
    • mi/hr
    • kn
  • Temperature
    • K
    • ºC
    • ºF
  • Volume
    • ML
    • kL
    • liter
    • dL
    • cL
    • mL
    • km³
    • m³
    • dm³
    • cm³
    • mm³
    • in³
    • ft³
    • yd³
    • mi³
    • acre ft
    • bushel
    • tsp
    • tbsp
    • fl oz
    • pt
    • qt
    • Imp gal
    • mcup

Convert Measurement

Convert measurement to unitType in unit.

convertMeasurement(variable measurement, enum unitType, text unit)

Network

Is Online

Returns a boolean based on whether the user has a working internet connection. This is an alias of the default Get IP Address action.

isOnline()

Get Local IP

Get the local IP of the user.

getLocalIP(enum ?type = "IPv4")

IP Types

  • IPv4
  • IPv6

Get External IP

Get the external IP of the user.

getExternalIP(enum ?type = "IPv4")

Set Cellular Data

Turn cellular data on or off.

setCellularData(boolean status)

Set Cellular Voice

Turn cellular voice and data on or off.

setCellularVoice(boolean status)

Set WiFi

Turn WiFi on or off.

setWifi(boolean status)

No-ops (noonce)

Comments

Comment actions have been abstracted into programming language style comments: Comments

Nothing

Do nothing and/or output nothing.

nothing()

Notification

Ask for Input

Ask for input with prompt, with optional inputType and defaultValue.

prompt(text prompt, enum ?inputType = "Text", text ?defaultValue)

Input Types

  • Text
  • Number
  • URL
  • Date
  • Time
  • Date and Time

Play Sound

Play sound input.

playSound(variable input)

Alert

Show an alert with title as the title and alert as the body.

alert(text alert, text ?title)

Confirm

Show a confirmation alert with title as the title and alert as the body. If the user presses cancel, the Shortcut will stop.

confirm(text alert, text ?title)

Show Notification

Trigger a custom notification.

notification(text body, text ?title, boolean ?playSound = true)

Numbers

Number

Create a number value.

number(number number)

Keep in mind the following statements have the exact same output. A Number action is created automatically for an integer literal, just as a Text action is created for a text literal.

@int = 5
@int = number(5)

The number() action should only be used to coerce text to a number.

@five = "5"
@fiveNum = number(five) /* 5 */

Format File Size

Format the size of the file to format.

fileSize(variable file, enum format)

File Size Format Units

  • Closest Unit
  • Bytes
  • Kilobytes
  • Megabytes
  • Gigabytes
  • Terabytes
  • Petabytes
  • Exabytes
  • Zettabytes
  • Yottabytes

Format Number

Format number with decimalPlaces number of decimal places.

formatNumber(integer number, integer ?decimalPlaces = 2)

Get Numbers

Get numbers from input.

getNumbers(variable input)

Random Number

Generate a random number with min as the minimum value and max as the maximum value.

randomNumber(integer min, integer max)

Shell

Run Shell Script

Run script with input as inputMode in shell.

runShellScript(text script, variable input, text ?shell = "/bin/zsh", text ?inputMode = "to stdin")

Input Modes

  • to stdin
  • as arguments

Script Editor

Run AppleScript

Run Apple Script script on input.

runAppleScript(variable input, text script)

macOS only

Run JavaScript for Mac Automation

Run JavaScript script on input.

runJSAutomation(variable input, text script)

Shortcuts

Get Shortcuts

Get all the user’s shortcuts.

getShortcuts()

Create Shortcut

Create a new Shortcut.

makeShortcut(text name, boolean ?open = true)

iOS 16.4+ only

Search Shortcuts

Search Shortcuts.

searchShortcuts(text query)

iOS 16.4+ only

Get Shortcut Detail

Get a detail of a Shortcut.

shortcutDetail(text detail, variable shortcut)

Details

  • Folder
  • Icon
  • Action Count
  • File Size
  • File Extension
  • Creation Date
  • File Path
  • Last Modified Date
  • Name

Open Shortcut

Open Shortcut with name name.

open(variable name)

Run Shortcut

Run Shortcut with name shortcutName, providing it with output.

run(text shortcutName, variable output)

Run Self

Run the current Shortcut providing it with output.

runSelf(variable output)

Stop Shortcut

Stop the Shortcut. Equivalent to exit or die in other languages.

stop()

System

Dismiss Siri

Dismiss Siri and continue.

dismissSiri()

Set Wallpaper

Set device wallpaper to image.

setWallpaper(variable image)

Get Wallpaper

Get device wallpaper.

getWallpaper()

iOS 16.2+ only

Variables

Variables are abstracted into variable statements, see Variables, Constants & Globals.

Windows

Find Windows

All arguments are optional.

Get all windows and sort by sortBy, order by orderBy, and limit by limit.

getWindows(enum ?sortBy, enum ?orderBy, integer ?limit)

Sort By

  • Title
  • App Name
  • Width
  • Height
  • X Position
  • V Y Position
  • Window Index
  • Name
  • Random

Order By

  • asc
  • desc

Move Windows

Move window to position.

moveWindow(variable window, enum position, boolean ?bringToFront = true)

Window Positions

  • Top Left
  • Top Center
  • Top Right
  • Middle Left
  • Center
  • Middle Right
  • Bottom Left
  • Bottom Center
  • Bottom Right
  • Coordinates

Resize Windows

Resize window to configuration.

resizeWindow(variable window, enum configuration)

Window Configurations

  • Fit Screen
  • Top Half
  • Bottom Half
  • Left Half
  • Right Half
  • Top Left Quarter
  • Top Right Quarter
  • Bottom Left Quarter
  • Bottom Right Quarter
  • Dimensions

X-Callback

Open X-Callback URL

Open X-Callback URL url.

openXCallbackURL(text url)

Open Custom X-Callback URL

Open X-Callback URL url, with success key successKey, cancel key cancelKey, and error key errorKey, and custom X-Success URL successURL.

openCustomXCallbackURL(text url, text ?successKey, text ?cancelKey, text ?errorKey, text ?successURL)