Using Shell Scripts

You can register script files or commands to listen for specific events that are broadcast by Templater. You can do this through the Templater Preferences dialog or the templater-options.json file if using the command line interface. Follow the steps under Registering shell scripts within the Templater Preferences dialog or Register shell scripts within the CLI options file.

Sample shell scripts are available at Dataclay's code repository on GitHub.

WARNING  Breaking Changes
As of Templater 2.7 the “For all commands, use job details as arguments” preference is deprecated. If your application makes use of the deprecated preference, your registered event scripts will fail. You must explicitly append arguments to shell scripts if they are necessary. Verify that you are explicitly passing arguments to your scripts, especially if you are using Templater’s command line interface. In the templater-options.json file, you can no longer use the “job_detail_args” property inside the “bot” object within the “prefs” object.

WARNING  MacOS Mojave 10.14 or later
MacOS has implemented security changes as of Mojave 10.14 to prevent unauthorized programs from running. This can interfere with running event shell scripts via Terminal. You may receive a Operation not permitted error message. If you receive this message when running an event script, you can try the following to resolve the issue: Pull down the Apple menu and choose ‘System Preferences’; Choose “Security & Privacy” control panel; select the “Privacy” tab, then from the left-side menu select “Full Disk Access”; Click the lock icon in the lower left corner of the preference panel and authenticate with an admin level login; Click the [+] plus button to add an application with full disk access; Navigate to the /Applications/Utilities/ folder and choose “Terminal” to grant Terminal with Full Disk Access privileges. (via OSXDaily)

ClosedRegistering shell scripts within the preferences dialog

  1. In the Templater preferences dialog, in the Bot Settings group, click Setup Shell Commands.
  2. In the Register Shell Scripts with Events dialog that opens, select a Templater event group to show available events associated with that group.
  3. register shell scripts
  4. Select either a Before event or After event. To enable a script to execute when a specific event is broadcast, you must select the event checkbox. If the checkbox is deselected, the script is disabled and cannot be edited.
  5. In the event field, enter the absolute path to the script or a full command as if it would be entered in a terminal or command prompt window.
    • For a script executable by the operating system, such as a Bash script (macOS) or Batch script (Windows), simply enter the absolute path to the script.
    • As a shortcut to enter the path to the script, click Choose script… and navigate to the location of the script. The path appears in the event field.
    • For a script requiring an interpreter such as NodeJS, Python, or PHP, use the full command syntax appropriate to the language used to write the script. For example, for a script created in NodeJS, enter
      node /Users/home/event-scripts/my-node-script.js
  6. If passing arguments to the script is required, do one or more of the following.
    • For passing explicit values, enter each value, separated by spaces, after the path or command within the event field. The following example, shows how you would pass Integer 512 and String 08-24-2018 as arguments to the registered Windows Batch script timestamp.bat.
      C:\Users\dev\event-scripts\timestamp.bat 512 '08-24-2018'
    • For passing pre-existing information, select a different item from the Append drop down menu, then click Append. Templater appends a corresponding, pre-existing, argument macro to the contents within the event field. Refer to the table under Pre-defined argument macros for a listing of all available pre-defined argument macros. The following example shows how you would pass three pre-existing pieces of information as arguments to the registered NodeJS script update-job.js: (1) $aep — the path to the currently processed After Effect project file, (2) $data_uri — the full URL or absolute path to Templater's connected data source, and (3) $now — a timestamp derived from the host machine's internal clock.
      node C:\Users\dev\event-scripts\update-job.js $aep $data_uri $now
    • For passing values from Templater's data source, create custom argument macros by prefixing column names or property keys with the $ symbol, and append those macros to the script path or full command within the event field. Learn more about Pre-defined argument macros and Using job details to event scripts below. The following example shows how you would pass the values of the album-name and release-date columns from Templater's connected spreadsheet to the registered Windows Batch script setup-folder.bat.
      C:\Users\dev\event-scripts\setup-folder.bat $album-name $release-date

  7. If the registered command or script must execute asynchronously as its own detached process enable the event group's Asynchronous checkbox.

    TIP By default, Templater executes registered commands and scripts synchronously which causes After Effects to wait until the script is done executing.

  8. To add additional shell scripts for other Templater events, repeat steps 2 through 6.
  9. When you are finished adding script information, click OK. The scripts are registered to Templater events.

ClosedRegistering shell scripts within the CLI options file

  1. In the templater-options.json file, in the bot object, set the specific event property to the absolute path of the file you want to run for that particular event. Alternatively, you can input any command as you would if you were in a terminal session, although this is not recommended for complex scripts.

    Refer to the following table for events that you can register a shell script to in the bot object. For detailed descriptions of each event, see Templater Events.
  2. Property in bot object Event Name Broadcast. . .
    "pre_cmd_data" Before data ...before data is retrieved
    "post_cmd_data" After data ...after data is retrieved
    "pre_cmd_batch" Before batch ...before main iteration loop starts
    "post_cmd_batch" After batch ...after main iteration loop completes
    "pre_cmd_job" Before job ...before job processing starts
    "post_cmd_job" After job ...after job processing completes
    "pre_cmd_udpate" Before update ...before layer updating starts
    "post_cmd_update" After update ...after layer updating completes
    "pre_cmd_output" Before output ...before rendering process starts
    "post_cmd_output" After output ...after rendering process completes
    "enable_cmd" Bot enabled ...when Bot is enabled
    "shutdown_cmd" Bot disabled ...when Bot is disabled

  3. If the registered command or script must execute asynchronously as its own detached process, set the appropriate asynchronous property key in the bot object to true.

    TIP By default, Templater executes registered commands and scripts synchronously which causes After Effects to wait until the script is done executing.


    Refer to the following table for determining which asynchronous property to set for the event that the script is registered to:
  4. Property in bot object Event for Asynchronous Execution
    "pre_cmd_data_async" Before data
    "post_cmd_data_async" After data
    "pre_cmd_batch_async" Before batch
    "post_cmd_batch_async" After batch
    "pre_cmd_job_async" Before job
    "post_cmd_job_async" After job
    "pre_cmd_udpate_async" Before update
    "post_cmd_update_async" After update
    "pre_cmd_output_async" Before output
    "post_cmd_output_async" After output
    "enable_cmd_async" Bot enabled
    "shutdown_cmd_async" Bot disabled

  5. To pass arguments to registered shell scripts in the templater-options.json file, do one or more of the following.
    • For passing explicit values, append each value, separated by spaces, to the script's absolute path or full command. The following example shows how you would pass Integer 512 and String 08-24-2018 as arguments to the registered Windows Batch script setup-folder.bat.

      NOTE  On Microsoft Windows, in the templater-options.json file, the backslash character and other special characters must be escaped using am additional backslash.

      { 
        "prefs" : {
                     "bot" : { "pre_cmd_data" : "C:\\Users\\dev\\event-scripts\\setup-folder.bat 512 '08-24-2018'" }
                  }
      }
    • For passing pre-existing information to the script, refer to the table under Pre-defined argument macros and append the corresponding arguments to script's absolute path or full command. Appended argument macros should be separated with spaces. The following example shows how you would pass three pre-existing pieces of information as arguments to the registered NodeJS script update-job.js: (1) $aep — the path to the currently processed After Effect project file, (2) $data_uri — the full URL or absolute path to Templater's connected data source, and (3) $now— a timestamp derived from the host machine's internal clock.
      { 
        "prefs" : {
                     "bot" : { "post_cmd_job" : "node C:\\Users\\dev\\event-scripts\\update-job.js $aep $data_uri $now" }
                  }
      }
    • For passing information from Templater's data source, enter a custom argument macro by prefixing a column name or property key with a $ symbol, and append that macro to the script's absolute path or full command. See Using job details to event scripts below for more information. The following example shows how you would pass the values of the album-name and release-date columns from Templater's connected spreadsheet to the registered Windows Batch script setup-folder.bat.
      { 
        "prefs" : {
                     "bot" : { "post_cmd_job" : "node C:\\Users\\dev\\event-scripts\\update-job.js $aep $data_uri $now" }
                  }
      }