Scripting Terminus



While Terminus makes it easy to directly interact with Pantheon from your command line, its real value is in scripting. By adding Terminus to your automated tasks, you can truly make Pantheon a part of your standardized workflow.

Consider the repetitive tasks you perform using the Pantheon Dashboard:

  • Can those tasks be executed by Terminus commands?
  • Can the values required by the commands be derived programmatically?

If so, you consider how you can turn the task into a script.

Authentication

Terminus needs to be authenticated in order to execute most commands. Before running any script you must ensure Terminus is authenticated with a machine token that has the proper permissions

Example Repositories

Bash Variables

One of the ways Terminus can be used in scripting is the generation of variables. In the example below, we use the output of terminus multidev:list to create an environment variable with all our multidev environments:

PANTHEON_MULTIDEV_LIST="$(terminus multidev:list -n ${TERMINUS_SITE} --format=list --field=Name)"

This example assumes the variable TERMINUS_SITE is already set. Now you can iterate through $PANTHEON_MULTIDEV_LIST using something like a while read loop to perform tasks on each multidev environment.

Example Bash Scripts

Take a backup of the live environment of all sites in an organization

Here's a more complete example. This script goes through every site in an organization, skips any that are frozen, and takes a backup of the Live environment:

#!/bin/bash

# Exit on error
set -e

# Stash org UUID
ORG_UUID="722c5f3b-....-6c8a"

# Stash list of all Pantheon sites in the org
PANTHEON_SITES="$(terminus org:site:list -n ${ORG_UUID} --format=list --field=Name)"

# Loop through each site in the list
while read -r PANTHEON_SITE_NAME; do
    # Check if the site is frozen
    IS_FROZEN="$(terminus site:info $PANTHEON_SITE_NAME --field=frozen)"

    # If the site is frozen
    if [[ "true" == "${IS_FROZEN}" ]]
    then
        # Then skip it
        echo -e "Skipping a backup of the site '$PANTHEON_SITE_NAME' because it is frozen...\n"
    else
        # Otherwise create a backup of the live environment of the site
        echo -e "Creating a backup of the live environment for the site '$PANTHEON_SITE_NAME'...\n"
        terminus backup:create $PANTHEON_SITE_NAME.live
    fi
done <<< "$PANTHEON_SITES"

This script requires that you set the variable ORG_UUID within the script itself. You can find the UUID using terminus org:list.

Save the PHP version of the live environment of all sites in an organization to a CSV file

Just like the example above, this example saves the output various Terminus commands to variables for reuse.

#!/bin/bash

# Save the desired org UUID or name
PANTHEON_ORG="722c5f3b-....-6c8a"

# Get a list of all sites in the org
PANTHEON_SITES="$(terminus org:site:list -n ${PANTHEON_ORG} --format=list --field=Name)"

# Name the CSV output file
CSV_FILE='pantheon-site-php-versions.csv'

# Add heading to the CSV file
# > is overwrite
echo 'site name,php version,frozen' > $CSV_FILE

# Loop through each site in the list
while read -r PANTHEON_SITE_NAME; do
    # Check if the site is frozen
    IS_FROZEN="$(terminus site:info $PANTHEON_SITE_NAME --field=frozen)"
    # If the site is frozen
    if [[ "true" == "${IS_FROZEN}" ]]
    then
        # The PHP version is unknown
        PHP_VERSION='FROZEN'
    else
        # Get the site's PHP version
        PHP_VERSION=$(terminus env:info $PANTHEON_SITE_NAME.live --field php_version)
    fi

    # Save the info to the CSV file
    # >> is append
    echo "$PANTHEON_SITE_NAME,$PHP_VERSION,$IS_FROZEN" >> $CSV_FILE
done <<< "$PANTHEON_SITES"

# All done
echo "Site PHP information has been saved to $CSV_FILE"

This script requires that you set the variable PANTHEON_ORG within the script itself. This can be either the organization name or UUID, both of which can be found using terminus org:list. Optionally, you can also update the name and path of the CSV file if you prefer something other than pantheon-site-php-versions.csv.