Terminus: A Rapid Introduction To Pantheon's Command Line Interface

If you've been using Pantheon, even for a short time, you'll know that the user dashboard provides significant power and control over all website management tasks. You can manage domains, migrate database changes, run backups, and apply code changes.

Being able to do so lets you create and manage sites across multiple environments, sites which work the same way, on the same hardware, with the click of just a few buttons.

It's also a massive time saver.

If, however, you’re responsible for five or more sites, you'll appreciate the inherent limitations in managing them this way. By doing so, only a limited number of sites can be managed simultaneously. And from here, the complexity only grows.

So, if you're looking for an approach that provides the ability to automate site administration tasks and free up your team for client-focused work, then you'll want to know about Terminus.

Terminus logo

In this post, we’ll walk through:

  • What Terminus is

  • The benefits command line tools bring to website management

  • How to get started using Terminus

What Is Terminus?

Terminus is Pantheon's command line automation software. It allows you to do anything you can do in the dashboard, including:

  • Updating code

  • Adding domains

  • Restoring backups

  • Managing payment methods

  • Importing media files and databases

Why Is Automation With Command Line Tools Beneficial For Website Management?

If you're not familiar with the command-line, you might not appreciate why it can be preferable to using a web interface. Specifically, it offers three key advantages.

Stability: Computers were designed for automating tedious, repetitive tasks. People weren't. By removing the need for people to repetitively run said tasks, scripts lower the risk of human error.

Automation and Scalability: Using services such as Cron for Linux, scripts can be automated to run on nearly any schedule imaginable. And when they're automated, your developers don't need to stay up till odd hours, avoid lunch breaks, or come in on weekends to do the work. Instead, they can spend their time where it counts, and where they're most effective.

Speed: How fast are your developers and admins with using the dashboard? Are they as quick as a script is? Can they do multiple changes—in parallel—without error? With a command-line interface, you can drastically reduce the time required to perform any maintenance task.

Installing and Authenticating Terminus

Before you can use it, you need to install it. You can do so with the following command:

curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar && php installer.phar install

Once installed, you can authenticate with a machine token generated from the dashboard by running the following command:

terminus auth:login --machine-token=‹machine-token›

If you have any difficulty with installation or authentication, please review the full documentation. Now that we are signed in, let's compare some Terminus commands against their equivalents in the dashboard. Specifically, let’s see how to do the following:

  • How to retrieve a listing of all your sites

  • How to get information about your sites

  • How to apply website updates to your sites

How to Retrieve a Listing of All Your Sites

Let's start by retrieving a listing of all the sites in your account.

To do so, run the command below.

terminus site:list

You'll see output similar to that below:

----------------------- -------------------------------- --------------- ----------- -------------------------------- --------------------- --------------------------------- ------------
Name ID Service Level Framework Owner Created Memberships Is Frozen?
----------------------- -------------------------------- --------------- ----------- -------------------------------- --------------------- --------------------------------- ------------
matthewsetter-development ca23e48d-bcd4-4a8b-8f7e-d0c2e5 free wordpress dbd9b390-a51e-475e-99cd-811b62 2016-11-05 13:26:23 dbd9b390-a51e-475e-99cd-811b622 false
ff1e14 282771 82771: Team
----------------------- -------------------------------- --------------- ----------- -------------------------------- --------------------- --------------------------------- ------------

This lists a range of information about each site on your account, including the name, framework, and when it was created. If you want to refine the information returned, such as only retrieving a specific set of fields, such as Name and ID, or render it in a specific file format, such as JSON or CSV, there are a switches which the command supports to allow for this.

Let’s now return only the Name and ID fields, and have the output render in JSON format. To do so, run the following command:

terminus site:list --fields=name,id --format=json

This will return the following output:

"ca23e48d-bcd4-4a8b-8f7e-d0c2e5ff1e14": {
"name": "matthewsetter-devtest",
"id": "ca23e48d-bcd4-4a8b-8f7e-d0c2e5ff1e14"

To find out all of the available switches, run the command terminus help site:list. While this might seem like quite a trivial example, it provides us with information for the next example.

How to Get Information About Your Sites

Now that you know what sites you have available, you can use that information to dig deeper and find out more about each of your sites by using the site:info command. This command shows information which the list command doesn’t, such as the holder type, holder id, and the latest commit on the upstream repository.

To find this information for matthewsetter-development, I’ll pass its name to the site:info command, as you can see below.

terminus site:info matthewsetter-development
--------------- -------------------------------------------------------------------------------------
ID ca23e48d-bcd4-4a8b-8f7e-d0c2e5ff1e14
Name matthewsetter-development
Label matthewsetter-development
Created 2016-11-05 13:26:23
Framework wordpress
Service Level free
Max Multidevs 10
Upstream e8fe8550-1ab9-4964-8838-2b9abdccf4bf: https://github.com/pantheon-systems/WordPress
PHP Version 5.5
Holder Type user
Holder ID dbd9b390-a51e-475e-99cd-811b62282771
Owner dbd9b390-a51e-475e-99cd-811b62282771
Is Frozen? false
--------------- -------------------------------------------------------------------------------------

How to Apply Updates to Your Sites

In this example, we're going to see how to apply core updates. First I can see available updates with terminus upstream:updates:list matthewsetter-development or terminus upstream:updates:status matthewsetter-development. Those will give me a list of updates a simple message for whether my site is outdated.

Updates can then be applied with terminus upstream:updates:apply matthewsetter-development. These commands are especially helpful if you want to apply core updates immediately after they become available. If you are going to automate the application of core updates, Pantheon has an example of how to pair that process with visual regression tests.

How to Retrieve Domain Information for a Site

Another handy feature is the ability to retrieve domain information for your site. To do so, you need the domain:list command. This displays domains associated with the environment. If I were to run it for my site’s test environment, by running terminus domain:list matthewsetter-devtest.test, it would return the following output:

-------------------------------------------- ----------------- -------------------------------------------- --------------
Domain DNS Zone Name Key Is Deletable
-------------------------------------------- ----------------- -------------------------------------------- --------------
test-matthewsetter-devtest.pantheonsite.io pantheonsite.io test-matthewsetter-devtest.pantheonsite.io
-------------------------------------------- ----------------- -------------------------------------------- --------------

Now what about one final command, domain:dns, which retrieves the recommended DNS settings for the environment. If I run it for the test environment of the site, it will return the following output:

-------------------------------------------- ------------- --------------------------------------------
Name Record Type Value
-------------------------------------------- ------------- --------------------------------------------
test-matthewsetter-devtest.pantheonsite.io CNAME test-matthewsetter-devtest.pantheonsite.io
-------------------------------------------- ------------- --------------------------------------------

In Conclusion (tl;dr)

That's been a brief introduction to Terminus, Pantheon's command line interface. By using it, in deference to the web dashboard, you will be able to significantly reduce the amount of time required to handle the routine admin tasks associated with running a website.

Whether you need to apply updates, import files and databases, or run regular backups, Terminus can handle this all for you. What's more, thanks to automation services it can be scheduled to run as often as is required, allowing developers to get back to what they do best—developing.

Automation allows you to feel confident that tasks will be completed the same way every time, across as many sites as you have, and as often as is necessary. This will both reduce your administration budget and increase your confidence and trust in the reliability and uptime of your website(s).

While there is a lot to Terminus, especially at first, I hope I've conveyed just how compelling the benefits are. I encourage you to give it a try so that you can simplify your website maintenance.

But be patient in the early days, and give your knowledge and skills a chance to grow. In time, the rewards will more than pay off the investment made.

You may also like:

Topics Website Technology, Development