You run Templater from the command line by putting three files in one folder and typing the name of the launcher script with the After Effects version after it. The three files are a rigged project, a configuration file called templater-options.json, and a launcher script. Everything else in this guide is about getting those three files right, because that is where the setup goes wrong.
This is a hands-on walk through the setup on Windows and on macOS. If you want the bigger question of who needs unattended rendering at all, we answered that in our explainer on automating After Effects rendering from the command line. Here we assume you have decided, and you want a working run. We also keep the options file to the parts you need on day one. A separate page, written to stand on its own, covers every key in that file.
What you need before you type anything
Start with the edition. Our help pages say Templater ships with command line control in the Bot edition. Jon at Dataclay confirmed on 26 October that the free trial contains all features, and that the command line is available in the trial too. So if you are evaluating, you can test this workflow before you buy. We do not state the length of the trial here, because the trial page is the place for that. See the Templater page for the current download and licensing details.
Next comes the machine. The launcher you use depends on the operating system, and the requirements differ.
On Windows, you invoke Templater through a PowerShell script named templater.ps1. PowerShell has to be allowed to run scripts for your user account. If your account is locked down, nothing below will work until that is sorted out, and the error you get will point at the script and not at Templater. Check this first so you do not spend an hour blaming the wrong thing.
On macOS, you invoke Templater through a shell script named templater.sh, and the docs list Python version 2.6 or later as a requirement. Every macOS release before 12.3 Monterey already had Python bundled. Apple stopped bundling Python 2.7 in macOS 12.3 and newer, so on a current Mac you install Python yourself. You can check by opening a new terminal and entering python –version. If a version number comes back, you are ready. If not, install it before going further.
Windows vs. macOS
What each platform needs to run Templater
- Launcher script
- Windowstemplater.ps1
- macOStemplater.sh
- Shell environment
- WindowsPowerShell
- macOSTerminal
- Extra requirement
- WindowsPowerShell must allow scripts for your user account
- macOSPython version 2.6 or later required
- Fix permissions with
- WindowsSecurity tab in file properties dialog
- macOSsudo chmod u+x templater.sh
The launcher you use depends on the operating system, and the requirements differ.
One historical note matters if you inherit an older setup. Before Templater 2.1.8, the launcher was a Microsoft Batch script on Windows and an AppleScript file on macOS. The docs say those older launchers still work with newer Templater versions but are no longer supported, and they recommend the newer scripts for a better command line experience. If someone left you a batch file or an AppleScript launcher, it will probably keep running. Replace it anyway the next time you touch the job, because an unsupported launcher is a risk you do not need.
The launcher scripts, plus sample options files and example code, come from Dataclay’s GitHub repository. You download them. If you skip that step, there is no templater.ps1 on your disk to run.
The folder: three files in one place
Create one working directory per template. Put these three things in it.
The first is an After Effects project file that is already rigged for Templater. It has to open in After Effects without error dialogs. That means every font, footage source and other dependency the project needs must be present on this machine. If you can open the file by hand and see a missing-font or missing-footage warning, the command line run will not fix it for you. It will hit the same problem with nobody there to click the dialog. A dialog nobody can see is a job that never finishes.
There is one more rule about the project file, and the docs mark it as a warning. If the Templater panel is showing when the project opens, you can get unexpected results from the command line. The project referenced in templater-options.json should have been saved with the Templater panel closed. So the habit is simple. Finish your rigging, close the panel in the workspace, save, and only then hand the file to the command line. We would also suggest you confirm the project versions cleanly from the panel first. The spot-check page in our docs says exactly that: make sure the project can be versioned without error using the Templater panel before you try the command line.
The second is the options file, templater-options.json. It tells Templater which project to open, where the data is, where the output goes and what task to run. You write it as plain JSON text and save it next to the project.
The third is the launcher, templater.ps1 on Windows or templater.sh on macOS.
The docs give a worked layout. On Windows, a folder named Weather Forecast under C:\Templates holds FiveDay.aep, templater-options.json and templater.ps1. On macOS, a folder named Weather Forecast under ~/Templates holds FiveDay.aep, templater-options.json and templater.sh. Those names are from the docs and they make a good template for your own naming. Keep the project, the options and the launcher together so that every relative thing is obvious when you come back to the job in three months.
A minimal options file you can start from
The options file has dozens of keys, and our sample from the docs shows all of them. You do not need all of them to start. Below is a trimmed file for a plain render job on Windows. It is a hypothetical example we assembled from the keys the docs describe, so adjust every path. We split it onto separate lines on purpose, one key per line, which keeps the file easy to read and easy to compare when something breaks.
{
"log_location" : "C:\\Templates\\Weather Forecast\\logs"
, "data_source" : "C:\\Templates\\Weather Forecast\\forecast.tsv"
, "aep" : "C:\\Templates\\Weather Forecast\\FiveDay.aep"
, "source_footage" : "C:\\Templates\\Weather Forecast\\footage"
, "output_location" : "C:\\Renders\\Weather"
, "render_settings" : "Draft Settings"
, "output_module" : "High Quality"
, "output_prefix" : "forecast_"
, "row_start" : 2
, "row_end" : 7
, "save_on_completion" : false
, "quit_on_completion" : true
, "tasks" : ["render"]
}Read it from the top and each line has a reason.
The log location is a folder, not a file. Templater writes its log files there, and you will want them the first time anything surprises you. The data source can be a tab-separated file, a Google Sheets feed URL, or a QUE campaign URL. The aep key is the absolute path to the project. The source footage key says where Templater imports footage from, and footage that is not local gets downloaded into a subfolder of that path named TEMPLATER DOWNLOADS. The output location is where renders from the After Effects render queue land. The docs advise against pointing it at a syncing folder such as Dropbox or Google Drive, so pick a plain local or network drive.
The render settings and output module values must match the template names in After Effects exactly, and they are case sensitive. If your output module is called High Quality in the Output Module Templates dialog, write it that way. A different capital letter is a different name.
The row range deserves a careful look. The defaults are row 2 to row 7. For a Google Sheets feed or a TSV file, the start row must be greater than 1, because row 1 is your header. The end row must be greater than the start row. If you set the range wrong, you will render the wrong slice of your data and nothing will tell you it is wrong. For a first run, keep the range small on purpose, because a three-row run tells you the pipeline works before you commit a long job.
One syntax rule trips people up. File paths in this file need their own syntax. On Windows, write each backslash twice, as in the example above. On macOS, use plain forward slashes. A single backslash in a JSON string is read as an escape, and the file will not parse the way you meant.
The last key is tasks, and it is where you say what Templater should do. A render job uses the word render. We cover the other task values below, and the companion page on the options file lists all of them.
Running it
Now the run itself. Open a new PowerShell terminal on Windows, or a new terminal session on macOS. Change into the folder that holds your three files. Then type the launcher name followed by the After Effects version.
On Windows, at the PowerShell prompt:
.\templater.ps1 -v '2020'On macOS, at the Terminal prompt:
./templater.sh -v '2020'The value after -v is the After Effects version you want Templater to use. Our docs example runs against the 2020 version, and the launcher help lists several other version strings with the same format, such as CC 2019 written in quotes. Use the one that matches the version installed on your machine. The launcher needs a supported After Effects version installed, and it will not run without one.
If you run the launcher without the required arguments, it prints its usage, its documentation and examples instead of running a job. That is useful. When you forget the syntax, type the launcher name alone, or add -h, and read the help.
There are two optional switches in that help. The -ui switch launches After Effects with its user interface. Without it, After Effects runs without a visible interface. For a first run on your own desk, adding -ui lets you watch what happens, which makes it far easier to see a stuck dialog. The -m switch launches After Effects as a new, separate process, which the help text says is useful if you want to run two or more versioning jobs at the same time. For a single job you do not need either one.
If the launcher does not execute at all, it is a permissions problem and not a Templater problem. On macOS, the docs suggest running sudo chmod u+x templater.sh so the script is executable for your user. On Windows, use the Security tab in the file properties dialog to change the permissions of templater.ps1 for your user. Both fixes are about the launcher file itself.
Then wait. Templater configures itself from the options file and works through its tasks with After Effects. When processing is done, the launcher prints two things: the last message that was logged to templater.log, and the last reported error found in templater.err. That final printout is your first stop. If it shows a clean last message and no error, go check the output folder. If it shows an error, you already have a place to start.
Reading the logs when a run does not produce output
Three files appear in the folder you set as log_location. templater.log holds logged messages. templater.err holds errors. templater.out is for watching Templater work as it happens.
Use templater.log when you want to read the history in an ordinary text editor. Use templater.out when you have a program that can examine a text buffer. On macOS you can follow it live in the terminal with tail -f templater.out, and you see each line Templater writes as it writes it. Keep that running in a second terminal window during your first few runs. It turns a silent job into one you can follow.
Each error in templater.err is written as a single-line object with five parts. There is a numeric code, a short description, the message After Effects threw if there was one, a details field with extra information and a suggestion, and a time stamp. The docs show an example. After Effects tried to import a corrupt or unsupported footage file, the code was 1001, the description was Error swapping footage source, and the details named the file and suggested importing it manually into After Effects to learn more. That is the right instinct. When Templater names a file, open that file in After Effects yourself and see what it says.
The docs list these error codes:
- 1 is an error starting the Templater application.
- 2 is an error initializing the Templater command line interface.
- 1001 is an error swapping a footage source.
- 1002 is an error downloading a remote footage source.
- 1003 means the footage file could not be found on the network.
- 2001 is a command line execution error.
- 2002 is a configuration file error.
- 3001 is an error conforming row data from a spreadsheet or TSV file.
- 4001 is a Google OAuth error.
- 4002 is a Google Drive retrieval error.
- 5001 is a Templater layout engine error.
- 6001 is an HTTP request error.
The code table is useful for more than diagnosis. The options file has a key named quit_on_errors, which takes an array of these codes. If Templater meets any code in that array, it force quits the task and After Effects. So if a missing footage file means the whole batch is worthless to you, list 1003 there and the job stops at the first occurrence instead of grinding through bad output. If you would rather let the job finish and review the damage afterward, leave the array empty, which is the default.
Error code reference
What each Templater error code means
| Code | Description | Area |
|---|---|---|
| 1 | Error starting the Templater application | Startup |
| 2 | Error initializing the command line interface | Startup |
| 1001 | Error swapping a footage source | Footage |
| 1002 | Error downloading a remote footage source | Footage |
| 1003 | Footage file could not be found on the network | Footage |
| 2001 | Command line execution error | Execution |
| 2002 | Configuration file error | Configuration |
| 3001 | Error conforming row data from a spreadsheet or TSV file | Data |
| 4001 | Google OAuth error | |
| 4002 | Google Drive retrieval error | |
| 5001 | Templater layout engine error | Rendering |
| 6001 | HTTP request error | Network |
When the run produces nothing or the wrong thing, work through it in this order. First, read the last message and the last error the launcher printed. Second, confirm the paths in templater-options.json, including the doubled backslashes on Windows. Third, open templater.log and templater.err in full. Fourth, check that the project opens in After Effects without a dialog and was saved with the Templater panel closed. Our docs give a similar order: verify the configuration file, then inspect the log and error files.
Exporting spot checks from the command line
A spot check is a still frame exported from a target composition so you can inspect the result before a long render. The command line can do this too, and it is a good way to prove a setup cheaply. We cover the feature itself in our page on preview modes and spot checks.
The steps from the docs are short. Make sure the project versions without error through the Templater panel. Configure templater-options.json. Set the spot check task to true and set every other task to false. Then run the launcher as before.
Here is a place where the saved docs describe the tasks setting in two ways. The sample file for Templater 3 shows tasks as an array of strings, so a spot check job would read as the single word spot_check in that array. The spot-check page describes a tasks object with true and false values for each property. The docs also state that Templater 3 and Templater 2 have different sample options files, sorted by operating system and version in the GitHub repository. So do not copy from memory. Download the sample file that matches your Templater version and follow its shape. We lean on the sample file you download over any single description, because the sample is what that version reads.
One more option from the docs. If you want renders or replicas in addition to spot checks, set render or replicate as the task, and turn on the matching spot-checking setting for rendering or for replication. The docs describe this as keeping one task and switching spot checks on alongside it. Whichever shape your version uses, the rule is the same: one task is set, and spot checks ride along only when you say so.
Data sources, other tasks and calling it from your own code
The command line works with local JSON files, local TSV files and Google Sheets documents. There is one exception that is worth knowing. A TSV file does not work when you use the command line to launch the Bot. If your plan involves the Bot, pick JSON or Google Sheets. For the how-to on feeds, see our page on using a URL feed or JSON file as a data source.
The tasks array holds more than render. The docs list replicate, bot_enable, spot_check, and four satellite tasks for registering, authorizing, deauthorizing and removing the current machine as a QUE Satellite. Multiple tasks can go in the array, and the docs say a single task is the most common choice. Registering and authorizing a machine together is the docs’ own example of two at once.
A few of these come with conditions. If you launch the Bot from the command line, the docs say to use the -ui switch, because enabling the Bot needs the After Effects interface, and to set quit_on_completion to false so Templater stays up. A Bot that quits the moment its first pass ends is not watching anything. To understand what the Bot does once it is running, read our page on the Templater Bot.
If you want to start renders from your own application, the docs say your application framework should be able to execute scripts in the operating system shell. That is all the integration there is. Your code calls the launcher with the version argument, the launcher reads the options file in its folder, and the logs tell you what happened. Because the options file lives in the project folder, one option is to write or update that file from your code before each call. Test that option on a small job before you rely on it.
For activation and deactivation from the command line, which uses the same options file with different task keys, see our activation guide. For installation prerequisites, see our system requirements page.
A first-run checklist, and the bottom line
Here is the whole procedure in the order we would run it on a new machine.
- Confirm you have the edition or trial that includes the command line, and download the launcher script and a sample options file from Dataclay’s GitHub repository.
- Confirm PowerShell may run scripts on Windows, or that Python is installed on a current Mac.
- Open the rigged project by hand. Fix every missing font and footage warning. Close the Templater panel. Save.
- Put the project, the options file and the launcher in one folder.
- Edit the options file with correct paths, a small row range and the render task.
- Run the launcher with -v and your version, adding -ui for the first run.
- Read the last message and last error the launcher prints, then check the output folder.
The command line is a good fit when another system, a script or a scheduled task has to start a render with nobody at the keyboard. It is a poor fit for a one-off job on your own desk, where the Templater panel is faster and shows you what it is doing. It also asks you to own a few things the panel hides: paths, a JSON file that is unforgiving about syntax, and log files you have to read.
The bottom line is short. Get the project clean, keep the three files together, run three rows before you run three thousand, and let the logs tell you what happened. If a run misbehaves, nothing in this setup is mysterious. It is three files, one command and a few text logs.
First-run procedure
Seven steps to a working command line run
-
Confirm edition and download scriptsConfirm you have the edition or trial that includes the command line, and download the launcher script and a sample options file from Dataclay’s GitHub repository.
-
Check permissions or PythonConfirm PowerShell may run scripts on Windows, or that Python is installed on a current Mac.
-
Clean and save the projectOpen the rigged project by hand.
-
Put three files in one folderPut the project, the options file and the launcher in one folder.
-
Edit the options fileEdit the options file with correct paths, a small row range and the render task.
-
Run the launcherRun the launcher with -v and your version, adding -ui for the first run.
-
Read the outputRead the last message and last error the launcher prints, then check the output folder.
We covered the setup from start to finish. Here are the questions we expect from someone about to try it.
Frequently Asked Questions
Does the Templater command line work in the free trial?
Yes. Jon at Dataclay confirmed on 26 October that the free trial contains all features, and that the command line is available in the trial. The trial adds a watermark to dynamic layers. Our help pages describe the command line as part of the Bot edition, so if you are unsure which edition your license covers, check the licensing page or ask Dataclay support before you build a production job around it.
Which launcher script do I use on Windows and on a Mac?
Since Templater 2.1.8, use templater.ps1 on Windows, run from PowerShell, and templater.sh on macOS, run from Terminal. Before 2.1.8 the launchers were a Microsoft Batch script and an AppleScript file. Those older launchers still work with newer versions of Templater, but they are no longer supported, so replace them when you can. You download the current scripts from Dataclay’s GitHub repository.
Why does the launcher print usage text instead of running my job?
The launcher needs its required arguments. Without them it prints its usage, documentation and examples. Add the After Effects version with the -v switch, in quotes, as in templater.ps1 -v ‘2020’. You can also type -h to see the help on its own. Run the command from the folder that contains the project, the options file and the launcher, because the launcher reads the options file from there.
The launcher will not run. What should I check?
Check permissions on the launcher file. On macOS, the docs suggest sudo chmod u+x templater.sh so the script is executable for your user. On Windows, change the permissions of templater.ps1 for your user from the Security tab in the file properties dialog, and make sure your account may run PowerShell scripts. On a current Mac, also confirm Python is installed, since Apple stopped bundling it in macOS 12.3.
Where do I find out why a command line run failed?
Start with the two lines the launcher prints when the run ends. They are the last message logged to templater.log and the last error found in templater.err. Then open both files in the folder you set as log_location. Use templater.out if you want to watch Templater work live, for example with tail -f on macOS. Error objects carry a numeric code, a description, the After Effects message and a details field.
Can I use a TSV file or Google Sheets with the command line?
Yes. The command line accepts local JSON files, local TSV files and Google Sheets documents. The one limit in our docs is that TSV will not work when you use the command line to launch the Bot. In that case, use JSON or Google Sheets. For a Google Sheets feed, copy the Feed URL from the Google Sheets Setup panel in the Templater panel and put it in the data_source key.
Why must the Templater panel be closed when I save the project?
Our docs warn that if the Templater panel appears when a project opens, you may get unexpected results when using that project from the command line. The project named in templater-options.json should be saved with the panel closed. Close the panel in the workspace, save the project, then run the launcher. Also confirm the project opens without any error dialogs for missing fonts or footage.
