Get Started

This section provides information on how to apply updates, deploy code, switch upstreams, and install Drush and WP-CLI with Terminus, as well as information on command structure and automatic site and environment detection.

Understand Commands

Basic Format

The basic format of a Terminus command is:

terminus command:subcommand <site>.<env>

More Information Command

You can find more information on any command:

terminus command:subcommand -h

List of Commands

You can get a list of all available commands:

terminus list

site.env

Terminus command structure typically includes <site>.<env> in order to determine the target site and environment to execute against. Note that the <> symbols are part of the example, and should not to be included in your commands. For example, running the env:clear-cache command for the Live environment of a site labeled "Your Awesome Site":

Automatic Site and Environment Detection

Terminus automatically detects the site and environment if a <site>.<env> parameter is not provided to a command that requests one. Terminus detects and operates from the local copy and current branch of the Pantheon site checked out at the current working directory.

git clone ssh://[email protected]:2222/~/repository.git mysite
cd mysite
terminus env:info

The example above is equivalent to terminus env:info mysite.dev.

Drush and WP-CLI

Pantheon supports Drush (Drupal) and WP-CLI (WordPress) commands remotely against a target site environment through Terminus. This is often faster and easier than leveraging such tools via local installations.

1. Use the basic command structure described above.

   The commands to invoke Drush and WP-CLI are:

   • remote:drush
   • remote:wp

2. Include -- followed by the Drush or WP-CLI command and all arguments. For example:

   

Refer to Drupal Drush Command-Line Utility and Use WP-CLI On The Pantheon Platform for more information.

Apply Updates

You can quickly apply updates from the command line with Terminus, including updates to:

• Core
• Contributed modules
• Themes
• Plugins

Upstream Updates (Core)

Pantheon maintains upstream updates for WordPress and Drupal. Updates can be applied after they have been merged into the upstream and become available for a site.

1. List available upstream updates:

   terminus upstream:updates:list my-site

   If the environment's connection mode is currently set to SFTP with uncommitted work you want to keep, commit before proceeding:

   terminus env:commit my-site.dev --message="My code changes"

   Warning:

   Warning

   The following command will permanently delete all uncommitted SFTP changes. Commit your work before proceeding if you want to keep SFTP changes.

2. Set the environment's connection mode to Git to pull updates into the site from Pantheon's upstream:

   terminus connection:set my-site.dev git

3. Apply available upstream updates for WordPress and Drupal core from the command line with Terminus:

   terminus upstream:updates:apply my-site

Module, Theme, and Plugin Updates

Apply updates to all contributed modules, themes, and plugins via Terminus by setting the environment's connection mode to SFTP and invoking Drush (Drupal) or WP-CLI (WordPress) update commands. You can then use Terminus to commit updates to a development environment on Pantheon.

Mass Update

Terminus supports third-party plugins that extend functionality by adding new commands. The following example demonstrates the Mass Update plugin to apply upstream updates (core updates) in bulk. Refer to the Plugins section for instructions on how to install Terminus plugins.

1. Install the Mass Update plugin, then use the --dry-run option to review available upstream updates without applying them:

   terminus site:list --format=list | terminus site:mass-update:apply --accept-upstream --updatedb --dry-run

   The output should be similar to this:

   [notice] Found 3 sites.
   [notice] Fetching the list of available updates for each site...
   [notice] 3 sites need updates.
   [warning] Cannot apply updates to novasoft-drupal because the dev environment is not in git mode.
   [DRY RUN] Applying 2 updates to jessiem-drupal7
   [DRY RUN] Applying 10 updates to superb-central

2. Resolve warning messages shown in the --dry-run output by setting the connection mode to Git for each applicable site:

   Warning:

   Warning

   The following command will permanently delete all uncommitted SFTP changes. Commit your work before continuing if you want to keep SFTP changes.

   terminus connection:set my-site.dev git

3. Review the output and then apply the mass update by removing the --dry-run option:

   terminus site:list --format=list | terminus site:mass-update:apply --accept-upstream --updatedb

Deploy Code

You can use Terminus to test a new set of changes by deploying code from development environments up to the Test environment while pulling the database and files down from Live.

1. Run the command below to deploy the code:

   terminus env:deploy my-site.test --sync-content --note="Deploy core and contrib updates"

2. Clear the site after each deployment:

   terminus env:clear-cache <site>.test

3. Test the changes, and then use Terminus to deploy code from Test up to Live:

   terminus env:deploy my-site.live --note="Deploy core and contrib updates"

4. Clear the site after each deployment:

   terminus env:clear-cache <site>.live

Reset Dev Environment to Live

There are a few scenarios where it may be useful to reset your Dev environment (codebase, files, and database) to your Live state:

• Development work that is not ready to go live has been committed directly to the Dev environment, blocking the deployment pipeline for other work ready to be deployed. After preserving work in progress on a local branch or on a Multidev environment,you can unblock deploys by resetting the Dev environment to reflect the Live environment state.

• Code changes were force-pushed or incorrectly merged into the Dev environment creating a large or complex Git history that you wish to undo.

• The state of the Dev environment is stale or out of date with the Live environment with many unneeded changes you want to abandon.

• The Dev environment has been seriously corrupted and you would like to cleanly reset it to Live.

Follow the steps below to reset Dev to Live.

1. Clone the site's codebase to your local machine if you have not done so already (replace awesome-site with your site name):

   terminus connection:info awesome-site.dev --fields='Git Command' --format=string

2. Automate the procedure for resetting Dev to Live by downloading the following bash script:

   reset-dev-to-live.sh

   #!/bin/bash
   
   #Authenticate Terminus
   terminus auth:login
   
   #Provide the target site name (e.g. your-awesome-site)
   echo 'Provide the site name (e.g. your-awesome-site), then press [ENTER] to reset the Dev environment to Live:';
   read SITE;
   
   #Set the Dev environment's connection mode to Git
   echo "Making sure the environment's connection mode is set to Git...";
   terminus connection:set $SITE.dev git
   
   #Identify the most recent commit deployed to Live and overwrite history on Dev's codebase to reflect Live
   echo "Rewriting history on the Dev environment's codebase...";
   git reset --hard `terminus env:code-log $SITE.live --format=string | grep -m1 'live' | cut -f 4`
   
   #Force push to Pantheon to rewrite history on Dev and reset codebase to Live
   git push origin master -f
   
   #Clone database and files from Live into Dev
   echo "Importing database and files from Live into Dev...";
   terminus env:clone-content $SITE.live dev
   
   #Open the Dev environment on the Site Dashboard
   terminus dashboard:view $SITE.dev
   

3. Execute the script from the command line within the root directory of your site's codebase:

   sh /PATH/TO/SCRIPT/reset-dev-to-live.sh

The Site Dashboard will open when the reset procedure completes.

Switch Upstreams

Every site has an assigned upstream to deliver one-click updates in the Pantheon Site Dashboard. Terminus can be used to manage this site-level configuration. There are a few scenarios where it may be useful to change a site's upstream:

• Convert existing sites from a default framework to a Custom Upstream.
• Convert existing sites from one Custom Upstream to another, for reasons such as:
  • Repository has been migrated from Bitbucket to Github, or vice versa.
  • Code has been refactored and moved to a new repository.
• Set an empty upstream to disable one-click updates for sites managed by Composer.

1. Run the command below to see all available upstreams:

   terminus upstream:list

   If your Workspace has a Custom Upstream, you can use Terminus to switch existing sites over to the common codebase:

   terminus site:upstream:set my-site "My Custom Upstream"

2. Use any valid identifier (upstream name, upstream machine name, upstream UUID) returned in terminus upstream:list to set a new upstream. For example, the upstream name "My Custom Upstream" is used above.

   As a safeguard, Terminus will prevent a framework switch such as moving from Drupal to WordPress or vice versa.

   Info:

   Note

   Refer to Serving Sites from the Web Subdirectory to set an empty upstream for Composer-managed sites.

3. Apply updates to the site to bring in the new codebase after setting the upstream. Refer to the example usage above for information on how to apply updates.

Troubleshoot Upstreams

Terminus Error: Permission to change the upstream of this site

If you encounter this error when setting a site's upstream:

terminus site:upstream:set $SITE $UPSTREAM
 [error]  You do not have permission to change the upstream of this site.

1. Confirm that the authenticated user account has the correct site-level permissions.

2. Check the currently authenticated user:

terminus auth:whoami

More Resources

• WordPress and Drupal Core Updates
• Custom Upstreams