Scripting with Terminus
Automate your workflow with scripting via Terminus.
Discuss in our Forum Discuss in SlackThis section provides information on how to automate your workflow with Terminus scripting.
Terminus makes it easy to directly interact with Pantheon from your command line, and provides additional value with scripting abilities. You can make Pantheon a part of your standardized workflow by adding Terminus to your automated tasks.
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, consider how you can turn the task into a script.
Authentication
Terminus must be authenticated before you can execute most commands. You must authenticate Terminus with a machine token that has the correct permissions before running a script.
Example Repositories
The Pantheon Example Terminus Auto Update Script demonstrates how you can use Terminus to automate plugin and theme updates for multiple sites.
The Example WordPress Composer repository (used by our Build Tools guide) uses Terminus to deploy staged changes to Multidev environments.
Bash Variables
Terminus can generate variables for scripting. In the example below, terminus multidev:list
is used to create an environment variable with all 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. You can iterate through $PANTHEON_MULTIDEV_LIST
using a while read
loop to perform tasks on each Multidev environment.
Interactive Prompts
Commands that normally require user interaction must be bypassed with the appropriate flag. The flags -y
or --yes
will bypass requests to confirm actions for most Terminus commands.
Example Bash Scripts
Take a backup of the Live environment of all sites in a Workspace
The script in this example goes through every site in a Workspace, skips any sites that are frozen, and creates a backup of the Live environment. This script requires that you set the variable ORG_UUID
within the script itself. You can find the UUID using terminus org:list
.
#!/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 [[ "1" == "${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"
Save the PHP version of the Live environment of all sites in a Workspace to a CSV file
This example saves the output of various Terminus commands to variables for reuse, similar to the example above.
This script requires that you set the variable PANTHEON_ORG
within the script itself. This can be either the Workspace 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
.
#!/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 [[ "1" == "${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"