How to automate your keyboard in Mac OS X with AppleScript

AppleScript is a natural language paradigm scripting language developed by Apple. It’s been around since 1993, when it first appeared in System 7. Although the future of AppleScript might be uncertain, it’s here now and it’s pretty darn useful.

In this guide we go over keyboard event scripting. This is a very rudimentary form of GUI scripting, which is itself a rather rudimentary technique. Although getting started is exceptionally easy, there are a few quirks that tend to show up when interacting with the Mac’s graphical interface in this manner. GUIs are typically designed for humans and aren’t great at handling a series of commands in rapid succession. It’s easy enough for a human to click a button again when the desired action didn’t happen for whatever reason. Not so easy to do that same thing with a script.

You may need to enable access for assistive devices before continuing. How exactly this is done varies a little bit between different versions of OS X. In 10.9 Mavericks, go to System Preferences --> Security & Privacy --> Privacy --> Accessibility, then enable access for assistive devices.

Getting started with keystroke and key code

The following script will start TextEdit and type out the standard “Hello world!” Pretty simple. Try it out in AppleScript Editor.

tell application "System Events"
  delay 0.5
  keystroke space using command down
  delay 0.5
  keystroke "Text"
  delay 0.5
  keystroke "Edit"
  delay 0.5
  keystroke return
  delay 1
  keystroke "Hello world!"
end tell

Everything between tell application "System Events" and end tell is run with System Events. tell application "System Events" is what allows us to script things like the keyboard.

delay 0.5 causes the script to pause for half a second. It’s generally a good idea to have a delay before any keyboard events. There’s a one second pause before keystroke "Hello world!" to give TextEdit enough time to start. If something isn’t working right the first thing I would check would be the delays.

keystroke space using command down presses the spacebar while holding down the command key. This activates Spotlight. keystroke return hits the return key, starting TextEdit. Finally, keystroke "Hello world! types “Hello world!` into the new TextEdit window.

This script is interesting because it demonstrates just how tricky it can be deciding where to put delays. Notice that in order to type “TextEdit” into Spotlight we’ve used two keystroke commands. There’s one for “Text” and another for “Edit”. We do this because Spotlight gets weird if we don’t. On my system, running Mavericks on a 2014 MacBook Air, if I use keystroke "TextEdit" Spotlight will open, “TextEdit” will be typed out and results listed, but then nothing else happens. Sometimes things don’t work in odd and subtle ways, making it difficult to figure out what’s going wrong. Delays usually fix these kinds of strange behavior. If it’s not working, try adding more delays. I think that’s a good rule of them when it comes to AppleScript keyboard scripting.

Slowing down keystroke entry with a loop

Here we use a loop, some variables, and a delay to slow down text entry to a more reasonable speed (although still very fast).

tell application "System Events"
  delay 0.5
  keystroke space using command down
 
  delay 0.5
  set textBuffer to "TextEdit"
  repeat with i from 1 to count characters of textBuffer
    keystroke (character i of textBuffer)
    delay 0.05
  end repeat
 
  delay 0.5
  keystroke return
 
  delay 1
  set textBuffer to "Hello world!"
  repeat with i from 1 to count characters of textBuffer
    keystroke (character i of textBuffer)
    delay 0.05
  end repeat
 	
end tell

This is a little more work than just using keystroke commands by themselves. But it’s worth it. So much more reliable.

When to use key codes

Sometimes we need to automate a key that doesn’t like to exist between quotation marks with a keystroke command. A good example of this are the arrow keys. To press the up arrow key, you’d write key code 126. Here’s a list of some good to know key codes.

delete 51
escape 53
left arow 123
right arrow 124
down arrow 125
up arrow 126

There are also keys that can be used with keystroke without quotes. These are probably easier for most people to remember than their key code equivalent. Remember, don’t use quotes with these.

keystroke return
keystroke space
keystroke tab