You start the Templater Bot from the command line by setting one task key in templater-options.json, launching the Templater script with the -ui flag, and then leaving the After Effects window alone. The part that decides whether the Bot picks up the right work is a separate group of keys called job_filter, and that group is the command line twin of a dialog you may only have clicked through once.
This page is for the person who has already run Templater from a terminal and now wants the Bot to sit on a render machine and watch a QUE campaign. We will cover the launch, the single flag that cannot be skipped, the way to turn the Bot off (which is narrower than you would hope), and every filter key that controls which QUE jobs the Bot touches. If you have not run the launcher at all yet, start with our command line rendering explainer and come back.
Starting the Bot: one task, one flag, one open window
The Bot is the edition of Templater that behaves like a background operator. Our explainer on what the Bot is covers the idea. Here we care about the mechanics of turning it on without touching the Templater panel.
Our support page gives the procedure in two steps. First, in the templater-options.json file, set bot_enable in the tasks group to true, and set every other task key to false. Second, run the Templater launch script from the command line using that configured options file. The launch itself is the same act as any other CLI run: you open a PowerShell terminal on Windows or a terminal session on OSX, change into the folder that holds your launcher and options file, and run templater.ps1 or templater.sh with the -v argument that names your After Effects version.
The docs give no reason for “all others false”, so here is our reading and not a documented explanation. The tasks key tells Templater what to do on this run, and our support pages describe the Bot as a mode where Templater keeps checking its data source. Switching render or replicate on as well would mix a one shot job into that. Follow the instruction as written.
There is one wrinkle you should know about before you copy any JSON. Our support pages describe the tasks setting in two ways. The page on enabling the Bot talks about keys inside a tasks object that are true or false. The root property key table lists tasks as an array of string constants, with values such as render, replicate, bot_enable, spot_check and the four satellite tasks. We do not want to guess which shape your options file uses, so open the options file that came with your launcher and follow the shape you find there. What matters is the outcome: bot_enable is the only task switched on.
The sketch below is an illustration, not a file to paste. It uses the array form from the root key table and leaves every path out on purpose.
{
"tasks": ["bot_enable"],
"quit_on_completion": false,
"log_location": "C:/Templater/logs"
}Two keys in that sketch deserve a reason. The root key table says that when you use bot_enable, quit_on_completion should be false. That fits what the Bot is, since a tool whose job is to wait for the next row should not quit after its first pass. The second key, log_location, is not required by the Bot docs, but it is the key that tells Templater which directory receives templater.out and templater.log. When a Bot runs unattended on a machine you are not sitting at, a known log folder is how you find out later what it did. We cover reading those files in a companion page on logs and error codes.
Now the flag. Our enabling page puts it in a warning: enabling the Bot through the CLI requires the -ui flag in the command line for all features to operate correctly. The root key table repeats it, saying that enabling the Bot requires an After Effects GUI to function properly. The launcher help text describes -ui in one line: when used, Adobe After Effects launches with a user interface.
That sounds backwards if you think of the Bot as headless. That is easy to miss. Our support pages say the Bot works without anyone operating the interface, but for the command line route After Effects itself still has to launch with its interface. If you start the Bot without it, the documentation says you may get a “Window does not have a constructor” error. That message is not obviously about the missing flag, which is why we mention it by name. If you ever see that text after launching the Bot, check your launch line for -ui before you check anything else.
A launch line then looks like the same launcher you already use, with -ui added. For example, on Windows with an options file configured for the Bot:
.\templater.ps1 -v '2020' -uiThe -v value is the After Effects version string the launcher expects, and our help text shows 2020 as one example. Use the string that matches the version installed on your machine. If the launcher will not run at all on OSX, our docs say to set permissions so the file is executable for your user. Our page gives the form sudo chmod u+x templater.sh for that.
The help text also lists an -m option, which launches After Effects as a new, separate process. It is described as useful when you want two or more versioning jobs running at once. Our pages do not say whether combining it with the Bot is supported, so we will not tell you it is. If you plan to run more than one Bot, read about the name key below first.
What the Bot does once it is running, and how to stop it
After the launch, After Effects opens with its interface, and Templater displays a dialog saying the Bot is enabled. That dialog is your control surface from this point. It has a Display Log button, which lets you view the log. A second button opens your source location. And it has the button that matters for shutdown: Disable Bot and Quit, which the docs write as Disable Bot and Quit After Effects in one place and Disable and Quit in another.
Here is the limit you must plan around. Our CLI page states that a bot_disable property key does not exist in Templater’s JSON options object. You cannot write a second options file that turns the Bot off. There are two ways out, and the docs name both. You click the disable and quit button in the open dialog, or you close the command prompt or terminal window and force close After Effects.
This has a practical consequence for unattended machines. If the render box is in a rack and nobody is logged in, we would expect the dialog to be out of reach, so the clean way to stop the Bot is likely a visit or a remote session to that machine. The blunt way is closing the terminal and force closing After Effects. The docs list it as one of the two options. Our pages do not say what a force close does to a render in flight, so if you can wait for the row to finish first, that is the cautious choice.
There is a second reason to prefer the dialog. The Bot property table includes shutdown_cmd and shutdown_jsx, which register a shell command or an ExtendScript file to run immediately after the Bot shuts down. The note on both keys says the script will not execute if After Effects undergoes a hard crash, and that it will execute if the user disables the Bot manually. If you rely on a shutdown script to clean up, such as updating a status somewhere, plan on stopping the Bot the way that lets it run.
The matching start hooks are enable_cmd and enable_jsx, which run immediately after the Bot is enabled. Each of these has an async partner key, shutdown_cmd_async for example, where true means asynchronous and false means synchronous execution.
The Bot property keys table also holds the settings that govern how the Bot watches its data. Here is what it says, in plain terms:
- goog_freq is how often, in minutes, the Bot checks for ready rows in a spreadsheet data source. The default is 0.3 and the stated minimum is 0.3, which is about 18 seconds.
- json_freq is how often the Bot checks for ready jobs in a JSON data source or in QUE. The default is 0.3 and the stated minimum is 0.2, about 12 seconds.
- max_queued is the maximum number of rows or jobs the Bot can retrieve each time it checks. The default is 20, and the notes say 20 is also the most it can queue at once.
- action_render, action_replicate and action_spot_check are booleans that default to false. They say whether the Bot outputs renders, replicas or spot checks when it finds ready work.
- name is a string identifier for this Bot instance. Use it if two or more Bots process the same data source, and leave it out if you run only one.
Read the action keys carefully, because they are what makes the Bot do anything with the work it finds. All three default to false. Set the ones you want before you rely on the Bot for output. The doc for action_spot_check adds a rule: if you want the Bot to export only spot checks, set action_spot_check to true and set action_render and action_replicate to false. If you want spot checks alongside renders or replicas, the docs point to the on_render and on_replicate properties in the spot_checking object instead.
Picking which QUE jobs the Bot processes with job_filter
When the data source is QUE, the job_filter group of keys defines what it asks QUE for. Our key table says these keys refer to the settings a person configures in the Job Selection Setup dialog, which opens from the Transport area of the Templater main panel. If you have set up a QUE selection by clicking, job_filter is the same choice written down so a launcher can read it. Our page on the QUE job states explains the render-status values these filters work against.
Each key in the group does one narrow thing.
job_filter.id retrieves a single job. When it is set, Templater retrieves the one QUE job that matches the value. The string has to be in the MongoDB ObjectId format, and the docs give 605d0a2efebbc63c132b6e29 and 61475eed4ebb3535effb4b6c as examples of valid IDs. This key is the right tool for rerunning one known job, such as a job you want to render again after fixing a template.
job_filter.status retrieves jobs whose render-status matches the string you give. The possible values the docs list are ready, queued, processing and done. For a Bot that should work through new requests, ready is the natural value. Filtering for done would hand the Bot finished work, which is a way to re-render a batch on purpose and not a way to keep a queue moving.
job_filter.properties is a group of key and value pairs you define. Templater retrieves the jobs that match those values. The docs give an example: set it to first_name jane and locale english, and Templater retrieves all QUE jobs whose first_name property matches jane and whose locale property is english. This is the key for splitting one campaign across several machines by the data inside the jobs. One Bot takes the english jobs and another takes a different locale.
job_filter.creation_start and job_filter.creation_end filter by creation date. Both use the MM-DD-YYYY format and both are strings. The rule is that they are a pair. If you set creation_start, creation_end must also have a value, and the same holds in the other direction. Setting only one is a configuration error waiting to happen.
job_filter.sort_rank is an array that sets the sort order of retrieved jobs. The default is the array containing _updatedAt. The docs list three of the properties it can sort on: _updatedAt sorts by when jobs were last modified, _createdAt by when they were created, and output by the job’s output property. You can combine them. Setting it to _updatedAt followed by last_name sorts first by the update time and then by last name.
job_filter.sort_dir sets ascending or descending order. The values are ASC and DESC, and the default is DESC. With a sort of last modified and a direction of DESC, the most recently touched jobs come first.
Three keys control paging, and they matter because of a default worth knowing. job_filter.page_number defaults to 1. The docs say that by default Templater processes only the first page of results it retrieves from QUE. prefs.jobs_per_page defaults to 5 and sets the maximum number of jobs Templater processes on any given page, with a note that a higher number may cause sluggish behavior. job_filter.additional_pages defaults to 0 and sets how many more pages of retrieved jobs Templater should process.
Put those three together and the consequence is clear. With the defaults, a single pass reads one page of five jobs. If your campaign has hundreds of ready jobs and you leave the paging keys alone, a pass will not walk through all of them in one go. You raise additional_pages, or you raise jobs_per_page, or look at how the Bot behaves across its repeated checks. How that interacts with the max_queued limit of 20 is something our pages do not spell out, so test it with a small campaign before you trust it with a large one. Our page on monitoring a Bot queue covers the watching side.
The filter keys are only half of what a QUE connection can carry. A second group, satellite, configures the machine as a QUE Satellite and mirrors the QUE Configuration dialog in Templater preferences. Its satellite.org_key holds your account’s organization key, found in the Account area of the QUE dashboard. The key is required if you set the tasks to one of the satellite tasks, such as sat_register or sat_auth. Its satellite.all_campaigns key, false by default, says whether the machine should retrieve jobs from any campaign in your account, which is useful when you want a Satellite to process jobs assigned to it wherever they live. And satellite.output_naming controls file names. The value unique names assets by the job’s _id. The value prepend names them by the _id and treats the job’s output value as a subfolder under the destination directory. The value override, the default, names assets by the job’s output value, and falls back to the _id if there is no output. If you use unique or prepend, expect file names like 605d0a2efebbc63c132b6e29.mov. Read our page on QUE Satellites before you put a machine in that role.
A worked example, and where the Bot is the wrong tool
Here is a hypothetical, labeled as one, so you can see how the pieces fit. Suppose a studio runs one QUE campaign that holds personalized greeting videos in two languages, and the jobs carry a property called locale. The studio owns two render machines and wants each to handle one language.
On the first machine, the options file turns on only the Bot task, sets quit_on_completion to false, names a log folder, and sets the job filter status to ready and the filter properties to locale english. It also sets the Bot name so the two instances have different identifiers. On the second machine, the file is identical except the locale value is the other language. Both machines are launched with the -ui flag, from a terminal that stays open. Each shows the enabled dialog, and each starts retrieving only the ready jobs that match its own locale.
Notice what that setup does and does not do. It splits work by a property you control, which is meant to keep two machines on different jobs. It does not balance load. Our own docs say nothing about spreading jobs by machine speed, and a machine that finishes early will sit idle while the other still has work. If balanced distribution matters to you, our page on assigning QUE jobs to a machine explains how assignment works.
Now the honest limits of the whole approach.
Because the docs require launching After Effects with a user interface, we infer the command line Bot needs a machine with a desktop session. Our pages do not say more than that, so if your plan was a truly invisible background service, check the -ui requirement against it first.
Stopping it needs a person or a force close. There is no stop key. If your operations team expects to shut a render box down with a script, you will be building a workaround, and the one the docs name is killing the terminal and After Effects.
The filters read QUE jobs. They do not apply to a Google Sheet or a local JSON file in the way the key table describes, because the table is the QUE property keys page. For those sources, the Bot reads rows marked ready in the render-status column, and our page on batches that fail mid-queue explains what the Bot writes back.
And the Bot is an edition feature. The Enable Bot button and the bot_enable task belong to the Templater Bot edition. If your license is for a smaller edition, the Bot functions will not be available to you. Command line access, per our team’s answer in October, is available in the free trial, which includes all features with a watermark on dynamic layers, so you can try this whole path before deciding. We are not stating a trial length here because we do not publish one on this page.
Before you leave a Bot running overnight, do a short run with a handful of ready jobs. Check three things in order. Did the enabled dialog appear, which proves the -ui flag worked? Did the right jobs change status, which proves the filter matches what you meant? And did the files land under the names you expected, which proves output_naming is set the way you intended? Our Templater page lists the editions if you need to confirm which one you hold.
The bottom line is short. Starting the Bot from a terminal takes one true task and the -ui flag, and stopping it takes a click or a force close. Deciding which QUE jobs it works on takes the job_filter keys, and the paging defaults mean you should set them on purpose. If you want a machine that waits for work and you are fine with a desktop session staying open, the command line Bot does that cleanly. If you need a remote off switch or load balancing, plan for those separately.
We covered the launch, the shutdown and the filters. These are the questions we would want answered before trusting it with a real campaign.
Frequently Asked Questions
Why does the Bot need the -ui flag if it runs without anyone operating it?
Our support pages say enabling the Bot through the command line requires the -ui flag for all features to operate correctly, because the Bot needs an After Effects interface to exist. Nobody has to click anything for each video, but the interface has to be present. Without it, the documentation says you may see a “Window does not have a constructor” error. If you see that message, check your launch line for -ui first.
Is there a key in templater-options.json that turns the Bot off?
No. Our CLI page states that a bot_disable property key does not exist in the options object. You disable the Bot by clicking the disable and quit button in the dialog Templater shows after launch, or by closing the command prompt or terminal window and force closing After Effects. If you rely on a shutdown script, note that the docs say it does not run after a hard crash but does run when you disable the Bot manually.
Which QUE jobs does the Bot pick up if I set no filter at all?
Our pages do not say what an empty job_filter selects, so we will not guess. What they do say is that the keys mirror the Job Selection Setup dialog in the Transport area of the Templater panel. Open that dialog to see the selection a fresh setup produces, then write the same choices into job_filter on purpose. Test with a small campaign before pointing a Bot at a large one.
How do I make the Bot work through more than the first page of QUE jobs?
By default Templater processes only the first page of results it retrieves from QUE. The page_number key defaults to 1, jobs_per_page defaults to 5 and additional_pages defaults to 0. Raise additional_pages to process more pages, or use page_number to begin at a later page. A higher jobs_per_page may cause sluggish behavior, according to the key notes. The Bot also has a max_queued limit of 20 per check.
Can two Bots read the same data source without colliding?
Our docs support running more than one Bot against the same data source and give the name key for that case, an identifier for each Bot instance. Splitting by job_filter.properties is a clean way to keep them apart, since each Bot takes jobs matching different values. Our pages do not describe load balancing, so a faster machine will not automatically take more of the work.
Do creation_start and creation_end have to be set together?
Yes. Both are strings in MM-DD-YYYY format, and the docs say that if you set one, the other must also have a value. creation_start keeps jobs created after the given date and creation_end keeps jobs created before it. Setting only one leaves the pair incomplete, so set both or neither.
Can I try the command line Bot in the free trial?
Yes, per our team’s answer in October, command line access is available in the free trial. The trial includes all features, with a watermark on dynamic layers. We do not state the trial length on this page. The Bot belongs to the Templater Bot edition, so confirm your edition before you commit.
