Scripting with Terminus
Automate your workflow with scripting via Terminus.
This 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.
Authenticate Terminus for Continuous Integration
You can run a complete backend authorization in Terminus by accessing Auth0 behind the scenes to positively identify the Terminus client with an OAuth token. Auth0 places limits on how many times this can be done in a given time period. Use your machine token to authorize Terminus sparingly to avoid exceeding Auth0 rate limits.
-
Running
terminus auth:login --machine-token=${TOKEN}to run a complete backend authorization. This process:-
Logs in your
machine-token -
Allows Terminus to create a cached session in the local user's $HOME folder (for example,
$HOME/.terminus/cache/session). Use this cached session token for repeated logins. The session file takes the following format:
-
-
Restore the session file in a CI context to stay logged in without re-authenticating every time. Instructions for specific CI pipelines are listed below.
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:
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. Also, -n flag could be used for non interactive mode.
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.
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.