Version: Deadline 7.2
One of the things that Deadline is known for is its fantastic user interface, or “UI” for short. Deadline’s UI makes the management of rendering and other compute tasks a breeze, and it has been a key factor in Deadline being adopted as the compute management tool of choice across multiple industries. But one of Deadline’s most powerful features is not in the UI. I like to think of it as Deadline’s secret weapon. And if you want to be a Deadline power user, then you need to know about it!
The feature I’m referring to is deadlinecommand, Deadline’s command line tool for doing pretty much anything that can be done in Deadline’s UI. In this blog post I’ll provide a gentle introduction to deadlinecommand so that you can take your first steps down the path of the Deadline power user.
For the examples here, I’ll be using the PowerShell terminal for Windows, and I’ll be using the standard Terminal (bash) for Linux from a Vagrant-generated Ubuntu virtual machine (the details of which are not important, but that’s why the username is vagrant in the Linux examples). In cases where the examples would be identical, only the Windows example is shown.
So feel free to open up a terminal window and follow along!
The first thing we need to do is make sure that the deadlinecommand program is accessible. We can check that by opening a terminal and typing in deadlinecommand. The operating system has a list of folders in which to look for programs called the path. If the folder that contains deadlinecommand has not been added to your system’s path, then you will see an error message. If the Deadline Client installer was run in the normal fashion, then thedeadlinecommand program can be run by first switching to the bin folder.
cd "\Program Files\Thinkbox\Deadline7\bin"
However, it is often easier to simply add the bin folder to the path so that deadlinecommand is accessible from anywhere. The commands to modify the path shown below will only apply to the current terminal window. Note that the capitalization of path differs from one OS to the next.
On Windows we can use:
$env:Path = $env:Path + ";" + "C:\Program Files\Thinkbox\Deadline7\bin"
On Linux we can use:
When deadlinecommand is run with no additional parameters, it shows a listing of all the sub-commands that can be run. If you scroll back through the listing, you’ll notice right away that the list of sub-commands is quite long, which should give you a sense of the power available via deadlinecommand.
Let’s try one of the fun sub-commands that shows some farm statistics. It’s called GetFarmStatistics. Simply type this sub-command after deadlinecommand:
Cool! Already you can start to see how easy it is to interact with Deadline from the command line. (Hint: There is similar command called GetFarmStatisticsEx. Try that one out too!)
If you work in an environment where jobs are processed on multiple platforms or where different Slaves access data from different servers, your farm might be using Deadline’s path mapping feature (Tools -> Configure Repository Options..., then select Mapped Paths from the list).
Here’s a handy way to test the path mappings. Note that you may not be able to follow along with this example if Mapped Paths are not configured in your repository.
deadlinecommand CheckPathMapping /Volumes/public/james/test
The mapping takes place from the perspective of the machine on which the command is run. Note the different output for the Windows and Linux machines above. This is handy for testing out new path mappings from the perspective of various machines on the farm.
Now let’s do something more interesting. Let’s list the Job Ids for all the jobs in the queue with the GetJobIds sub-command:
Now let’s use the GetJob sub-command to get details about one of these jobs. Copy one of the Job Ids from the listing, and paste it into the following command (replace the [Job Id Here] with the one you copied from your listing). The result is a readout showing a bunch of setting-value pairs of information about the job.
deadlinecommand GetJob [Job Id Here]
Using those setting-value pairs, we can retrieve Job Ids that meet specific criteria. To do that we’ll use the GetJobIdsFilter sub-command. Before we do, let’s get help on this command by using the Help sub-command.
deadlinecommand Help GetJobIdsFilter
So we can filter the list of Job Id’s returned by providing one or more filters specified in a setting=value fashion. Let’s see if we can list the Ids of all completed jobs submitted by Dwight.
deadlinecommand GetJobIdsFilter UserName=dwight JobStatus=Completed
It appears that Dwight has been very productive! I have decided that I would like to take credit for some of Dwight’s hard work. Let’s change the UserName of one of Dwight’s completed jobs to my UserName. Note that there is no =sign between the setting’s name and its new value:
deadlinecommand SetJobSetting [Job ID Here] UserName james
...and done! Wow, look how my productivity just shot through the roof! Ok, plagiary is probably not the best path to career advancement. (And for the record, I switched the UserName setting back to Dwight’s UserName.) But from this example you should get a sense of the great power of deadlinecommand. And with great power comes great responsibility.
A very powerful feature of deadlinecommand is the ability to submit jobs to the queue. Jobs can be submitted individually or in batches. This subject is beyond the scope of this “gentle introduction”, but if you want to learn more about how to do this, check out the documentation here.
All Good Things
So, you might be wondering why someone would do these operations from the command line when they could be done just as easily from the UI. If you happen to be logged into a machine that is running in headless mode, thendeadlinecommand can be a convenient way to get at Deadline-related information without having to move back to a Desktop machine. But a more significant reason is that deadlinecommand can be used as a building block for automation.
It can be called from shell scripts like PowerShell (Windows) and bash (Linux) and from Python or any programming/scripting language that can issue system commands and retrieve the output. The output can then be used to make decisions and take further actions. In other words deadlinecommand is a building block that allows you to create complex, automated behaviors for your farm that are customized to your pipeline.
If you would like to see some examples of how deadlinecommand can be used to do many interesting things, check out the Thinkbox’s public GitHub repository.