Keyboard Maestro Wiki

User Tools

Site Tools

Trace: • Search_Strings • SCREEN • Windows
action:Execute_a_Shell_Script

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
action:Execute_a_Shell_Script [2021/10/14 08:45] – peternlewisaction:Execute_a_Shell_Script [2025/09/12 07:02] (current) – [Quoting Strings] peternlewis
Line 7: Line 7:
 * It is best to always specify the language using the `#!` at the front of the script. * It is best to always specify the language using the `#!` at the front of the script.
 * The script is executed with the `sh` shell, so if you want to use another language, or use any special kinds of shell-specific syntax, then you should specify the language. * The script is executed with the `sh` shell, so if you want to use another language, or use any special kinds of shell-specific syntax, then you should specify the language.
 +* The shell is a non-login shell, so configuration files (like .bashrc) will not be run - in particular, this means you will not have much in the PATH (see [[#Path_in_Shell_Scripts|below]] for more information).
 * For more details and examples, see [[https://forum.keyboardmaestro.com/t/impact-of-macos-catalina-defaulting-to-unix-shell-using-zsh/15503/12?u=jmichaeltx|How to Use Shebang at Top of Shell Script]] * For more details and examples, see [[https://forum.keyboardmaestro.com/t/impact-of-macos-catalina-defaulting-to-unix-shell-using-zsh/15503/12?u=jmichaeltx|How to Use Shebang at Top of Shell Script]]
  
Line 16: Line 17:
  
 If the script fails, the action will fail (v9.0+), potentially aborting the macro. If the script fails, the action will fail (v9.0+), potentially aborting the macro.
 +
 +Keyboard Maestro sets the environment variables for the script to include all your variables, using a prefix of `KMVAR_` and your variable name with spaces changed in to underscores (‗). For example, your Keyboard Maestro “File Name” variable will be available as the environment variable `KMVAR_File_Name`.
 +
 +Keyboard Maestro also provides (v10.0+) a number of environment variables that contain information about the executing macro. These include:
 +
 +^environment variable^meaning^
 +|`KMINFO_MacroName`|The name of the parent executing macro|
 +|`KMINFO_MacroUUID`|The UUID of the parent executing macro|
 +|`KMINFO_MacroGroupName`|The name of the macro group containing the parent executing macro|
 +|`KMINFO_MacroGroupUUID`|The UUID of the macro group containing the parent executing macro|
 +|`KMINFO_ThisMacroName`|The name of the executing macro|
 +|`KMINFO_ThisMacroUUID`|The UUID of the executing macro|
 +|`KMINFO_ThisMacroGroupName`|The name of the macro group containing the executing macro|
 +|`KMINFO_ThisMacroGroupUUID`|The UUID of the macro group containing the executing macro|
 +|`KMINFO_TriggerTime`|The [[/unixtime|unixtime]] the parent macro started executing|
 +|`KMINFO_TriggerBase`|The type of the trigger that started the parent macro|
 +|`KMINFO_Trigger`|The trigger description of the trigger that started the parent macro|
 +|`KMINFO_TriggerValue`|the value associated with how the parent macro was triggered|
 +|`KMINFO_ActionResult`|The success or failure of the immediate past action|
 +|`KMINFO_LastWindowID`|The window ID of the most recently displayed Keyboard Maestro Engine window|
 +|`KMINFO_PromptWithListText`|The text typed in the most recently executed [[action:Prompt_With_List|Prompt With List]] action|
 +|`KMINFO_PasteByNameText`|The text typed in the most recently executed [[action:Paste_by_Name|Paste by Name]] action|
  
 ==== Using Keyboard Maestro Variables ==== ==== Using Keyboard Maestro Variables ====
  
-=== Most Languages like bash, perl, ruby ===+Keyboard Maestro variables are included in the environment of the script, with the prefix `KMVAR_` and spaces in the name replaced with underscores (‗), 
 + 
 +By default, all variables are included, but you can select No Variables, or specific variables as desired using the popup menu next to the script (v11.0+). 
 + 
 +=== Most Shell Languages like bash ===
  
 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 (‗). 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 (‗).
Line 109: Line 136:
 The results of a shell script can be: The results of a shell script can be:
  
-  * Ignored. +{{page>include:ScriptOutput#}}
-  * 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. +
-  * Appended to a variable (v9.0+). +
-  * 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 [[manual:Scripting#AppleScript|set Keyboard Maestro variables]].+If the output is going to a clipboard or a file, the downloaded data can be an image (v11.0+). 
 + 
 +If you want to return multiple values from a script, then you can use AppleScript (via `osascript`) to [[manual:Scripting#AppleScript|set Keyboard Maestro variables]].
  
 ===== Examples ===== ===== Examples =====
Line 154: Line 174:
 It is bash that has processed the variable substitution for $KMVAR_witchPref, split the line in to seven parts, processed the backslash in "Application\ Support" and then executed the defaults tool with the seven parts as arguments (the command itself is the 0th argument, normally mostly ignored by tools). It is bash that has processed the variable substitution for $KMVAR_witchPref, split the line in to seven parts, processed the backslash in "Application\ Support" and then executed the defaults tool with the seven parts as arguments (the command itself is the 0th argument, normally mostly ignored by tools).
  
-So the problem is that the word-breaking, variable substitution, de-quoting and de-backslash is all happening at as the line is processed by bash, after which you are left with quotes from within variable substitution, but they no longer have any meaning, they are just characters.+So the problem is that the word-breaking, variable substitution, de-quoting and de-backslash is all happening as the line is processed by bash, after which you are left with quotes from within variable substitution, but they no longer have any meaning, they are just characters.
  
 So variables that are meant to be a single parameter should be surrounded by double quotes in the line, but not contain quotes in the variable, and generally you do not want to pass multiple parameters within a single parameter.  So instead, perhaps set one variable to the setting name, and one variable to the type and one variable to the value, and then use a command like this: So variables that are meant to be a single parameter should be surrounded by double quotes in the line, but not contain quotes in the variable, and generally you do not want to pass multiple parameters within a single parameter.  So instead, perhaps set one variable to the setting name, and one variable to the type and one variable to the value, and then use a command like this:
Line 201: Line 221:
  
 The tr command will replace `\r` or `\n` line endings with a nul character, and the `xargs -0` command will read that, split the arguments at the nul character, and pass them to the specified command (in this case `ls -l`. Note that xargs has a limit to the number of arguments it will pass, so for large numbers of arguments it may run the command multiple times with subsets of the arguments - read the `xargs` man page for more details. The tr command will replace `\r` or `\n` line endings with a nul character, and the `xargs -0` command will read that, split the arguments at the nul character, and pass them to the specified command (in this case `ls -l`. Note that xargs has a limit to the number of arguments it will pass, so for large numbers of arguments it may run the command multiple times with subsets of the arguments - read the `xargs` man page for more details.
 +
 +Also note that shell globing happens after variable expansion, and so if the variable contains `*` characters they will be expanded by the shell by matching file names in the current directory. To avoid this, you can turn off globing by using the -f option when executing bash - that is, start your script with `#!/bin/bash -f`.
  
 ===== Path in Shell Scripts ===== ===== Path in Shell Scripts =====
Line 225: Line 247:
 Any Keyboard Maestro variable that starts with `ENV_` will automatically be set as the as the corresponding environment variable (without the usual `KMVAR_` prefix). So if you set your path in the `ENV_PATH` Keyboard Maestro variable, the `PATH` environment variable will be set from it. Any Keyboard Maestro variable that starts with `ENV_` will automatically be set as the as the corresponding environment variable (without the usual `KMVAR_` prefix). So if you set your path in the `ENV_PATH` Keyboard Maestro variable, the `PATH` environment variable will be set from it.
  
-You can set this Variable manually in the [[manual:manual/Preferences#Variables_Preferences|Variable Preferences Panel]] in Keyboard Maestro. Once the `ENV_PATH` variable is set, it will remain in your Keyboard Maestro variable until/unless you delete it, and remain available to every Execute a Shell Script action that you might use in the future.  So you don’t need to set it in every Macro.+You can set this Variable manually in the [[manual:Preferences#Variables_Preferences|Variable Preferences Panel]] in Keyboard Maestro. Once the `ENV_PATH` variable is set, it will remain in your Keyboard Maestro variable until/unless you delete it, and remain available to every Execute a 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. 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 [[https://www.perl.org/ | Perl]] with a custom library search path in the Execute a Shell Script action, you can also create a Keyboard Maestro variable `ENV_PERL5LIB` that will set the [[http://perldoc.perl.org/perlrun.html#ENVIRONMENT|PERL5LIB environment variable]]. For example, if you want to use [[https://www.perl.org/ | Perl]] with a custom library search path in the Execute a Shell Script action, you can also create a Keyboard Maestro variable `ENV_PERL5LIB` that will set the [[http://perldoc.perl.org/perlrun.html#ENVIRONMENT|PERL5LIB environment variable]].
 +
 +(!) Note that if in the action you exclude the ENV_ variables (including potentially the ENV_PATH) from being included in the environment (eg by selecting //Include No Variables//), this will result it them not being included and thus not setting the corresponding environment variables.
 +
 +===== Working Directory =====
 +
 +The working directory for any executed scripts will be set from the Keyboard Maestro `ENV_PWD` directory (v10.0+), or default to the root directory (`/`).
 +
  
 ===== Execute Script From Other Apps ===== ===== Execute Script From Other Apps =====
Line 272: Line 301:
 === Actions === === Actions ===
  
 +* [[action:Execute_a_Swift_Script|Execute a Swift Script]]
 * [[action:Execute an AppleScript|Execute an AppleScript]] * [[action:Execute an AppleScript|Execute an AppleScript]]
 * [[action:Execute an Automator Workflow|Execute an Automator Workflow]] * [[action:Execute an Automator Workflow|Execute an Automator Workflow]]
action/Execute_a_Shell_Script.1634201113.txt.gz · Last modified: by peternlewis
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki