User Tools

Site Tools


Execute a Shell Script

The Execute a Shell Script action executes a specified shell script, either from a file or from the script embedded in the action.

To execute the script from an external file, choose the “Execute Script File” in the choices for script location.

You can choose what input (stdin) to send to the script (v8+) as well as where the output should go.

Using Keyboard Maestro Variables

In your script, use this format: $KMVAR_[variable_name]

where [variable_name] is the name of your Keyboard Maestro Variable, but with spaces in the name replaced with underscores ().

For example: File Name would be formated as $KMVAR‗File‗Name.

If your variable already has underscores, you can use it as is.

Note that you can only read these environment variables. You cannot write to them (or more accurately, you can write to them but that will not change the Keyboard Maestro variables that they were created from).

Passing Paths in Variables

If you are passing a file/folder path in a Keyboard Maestro Variable, then it is best to put the Variable reference in double quotes so that spaces in the path will work, like this:

cat "$KMVAR_File_Path"

This must be a full path. If the path starts with a tilde (~), then you must first convert it to a full path using the Filter, Expand tilde (~) paths Action BEFORE the Execute Shell Script Action.

For more info, see an excellent, detailed discussion of How To Quote Paths by @ccstone.

Action Gear

The Action (gear) menu includes the following options:

  • Trim Results — removes white space from the start and end of the scripts results.
  • Include Errors — include stdout and stderr results from the script.

Output of Results

The results of a shell script can be:

  • Ignored.
  • Displayed in a floating window.
  • Displayed briefly in a Notification.
  • Displayed large across the screen.
  • Typed in to the current selection.
  • Pasted in to the current selection.
  • Saved to a variable.
  • Saved to the system or a Named Clipboard.
  • Asynchronously ignored — the action runs while the macro continues on.

If you want to return multiple values from a script, then you can either use AppleScript (via osascript) to set Keyboard Maestro variables.


For example, you could have a shell script date display briefly in the Notification Center every hour, or use a hot key to type the results directly into your text editor.

You can also use the clipboard by piping from pbpaste and to pbcopy.

Quoting Strings

Proper quoting of strings in a Shell Script is often a challenge.

For a discussion on how to quote a string, see this Keyboard Maestro Forum post by @PeterNLewis.

Path in Shell Scripts

In essence, the default path in a Keyboard Maestro Execute Shell Script is the base path for the system:


that is the script will search for tools in the /usr/bin directory, then in the /bin directory, then /usr/sbin and finally /sbin. Only tools installed by the system will be in these directories - any tools you have installed will almost certainly be elsewhere and so not found by default because:

  • shell scripts are executed in non-interactive mode (see the INVOCATION section of the bash man page), the only path preset by default is the system path.
  • Thus, your tools or files may not be automatically accessible.
  • The $PATH environment variable you may have set in Terminal is not used.
  • None of your profile scripts (like ~/.profile) will be executed.
  • Custom environment variable settings will not be applied, including any settings for tool-specific environment variables like PERL5LIB.

How To Set a Path

  • If you need access to tools (executables) or files that you installed (not part of the system installation),
    You will need to do one of the following:
    • Use an explicit, full path to the tool or file.
      See Passing Paths in Variables in the above section.
    • Set the $PATH environment variable within each Execute Shell Script action.
    • Set ENV_PATH (the Keyboard Maestro Path Variable) prior to the Execute Shell Script Action.
      • The path defined in this Variable will automatically apply to every Execute Shell Script, without need for further reference. It will work just like your $PATH works in the Terminal app.
      • You can set this Variable manually in the Variable Preferences Pane of the Keyboard Maestro App Preferences.
      • Once the ENV_PATH Variable is set, it will remain in your Keyboard Maestro Variable set (until/unless you delete it), available to every Execute Shell Script Action that you might use in the future. So you don't need to set it in every Macro.
      • If your tool requires other environment variables to be set you can set them as well by creating an appropriate Keyboard Maestro variable with ENV_ at the front.
        • For example, if you want to use Perl with a custom library search path in a Execute Shell Script action, you can also create a Keyboard Maestro Variable ENV_PERL5LIB that will set the the PERL5LIB environment variable for each Execute Shell Script.

Setting the ENV_PATH Keyboard Maestro Variable

A shell script path that will work for many users is:


Of course, if you have tools or files you installed elsewhere, then you would need to include the path to those in this path statement, IF you plan to use any of those tools/files in a Execute Shell Script Action.

You can create the ENV_PATH Variable one time using the Variable Preferences Pane of the Keyboard Maestro Preferences.

  • Add a variable named ENV_PATH and set its value.
  • Once set, it will remain unchanged until you change or delete it.

For a good discussion about this see:

Execute Script From Other Apps

When you execute a shell script from other apps, like, the shell does NOT have access to the Keyboard Maestro Engine environment, and thus it does NOT know anything about Keyboard Maestro Variables.

In order to access Keyboard Maestro Variables in these scripts, you must use a tool like osascript.

⚠️ Note that you do NOT need to replace spaces with underscores in your Variable name in this case, since you are ultimately using AppleScript in the Shell Script.

Here is a simple example that works with Keyboard Maestro Ver 6+ to get a variable:

osascript -e 'tell application "Keyboard Maestro Engine" to get value of variable "My KM Var"'

If you are using Keyboard Maestro 7.1+ you can use the new simpler command to get a variable:

osascript -e 'tell application "Keyboard Maestro Engine" to getvariable "My KM Var"'

To set a variable (and create if needed) with Ver 7.1+ you can use this:

osascript -e 'tell application "Keyboard Maestro Engine" to setvariable "My KM Var" to "Some new value"'

Here is a more comprehensive example, providing error handling:

read -r -d '' theAppleScript <<'EOF'
   tell application "Keyboard Maestro Engine"
      set kmVarName to "My KM Var"
      tell variable kmVarName
         if it exists then
            return its value
            return "Error → Keyboard Maestro variable '" & kmVarName & "' does not exist!"
         end if
      end tell
   end tell

osascript -e "$theAppleScript";

See Also



action/Execute_a_Shell_Script.txt · Last modified: 2017/09/06 23:55 by peternlewis