Getting Started with Terminus: An Introduction

By /

Okay, here is the detailed article on getting started with Terminus.

Getting Started with Terminus: An Introduction to Pantheon’s Command-Line Powerhouse

In the world of modern web development and DevOps, efficiency, automation, and control are paramount. For users of the Pantheon WebOps platform, managing Drupal and WordPress sites often involves interacting with the platform’s dashboard. While the web interface is powerful and user-friendly, there are times when developers and administrators need a faster, more scriptable, and ultimately more powerful way to interact with their sites and environments. This is where Terminus, Pantheon’s official command-line interface (CLI), steps in.

Terminus is an indispensable tool for anyone serious about developing, deploying, and managing sites on Pantheon. It unlocks a level of control and automation that goes far beyond what’s easily achievable through the web dashboard alone. Whether you’re clearing caches, deploying code, cloning databases, managing team members, or integrating Pantheon operations into complex CI/CD pipelines, Terminus provides the commands to make it happen directly from your terminal.

This comprehensive guide aims to be your starting point for mastering Terminus. We’ll cover everything from the fundamental concepts and installation to core commands, practical workflows, and best practices. By the end of this article, you’ll understand why Terminus is so crucial and how you can leverage it to streamline your Pantheon workflows significantly.

Who is this guide for?

This guide is primarily aimed at:

  1. Developers: Building and maintaining Drupal or WordPress sites on Pantheon.
  2. Site Builders: Configuring and managing site features and content.
  3. System Administrators / DevOps Engineers: Responsible for site deployment, maintenance, backups, and automation.
  4. Agency Teams: Managing multiple client sites on the Pantheon platform.

While some familiarity with command-line interfaces (like Bash, Zsh, or PowerShell) is helpful, we’ll explain the concepts clearly. A Pantheon account and at least one site on the platform are necessary to follow along with the practical examples.

What will we cover?

  1. What is Terminus and Why Use It? Understanding the core purpose and benefits.
  2. Prerequisites: What you need before you start.
  3. Installation: Getting Terminus set up on your local machine (macOS, Linux, Windows).
  4. Authentication: Securely connecting Terminus to your Pantheon account.
  5. Understanding Terminus Command Structure: Learning the syntax and how to find help.
  6. Core Terminus Functionality:
    • Site Management (Listing, Info, Team)
    • Environment Management (Listing, Info, Creation, Deletion, Connection Modes)
    • Code Management & Deployment (Workflow, Commits, Deploys)
    • Database Management (Backups, Restoration, Cloning)
    • Files Management (Backups, Restoration, Cloning)
    • Executing Remote Commands (Drush & WP-CLI)
  7. Workflow Automation & Scripting: Combining commands for efficiency.
  8. Advanced Topics & Best Practices: Plugins, configuration, security, performance.
  9. Troubleshooting Common Issues: Getting unstuck when things go wrong.
  10. Conclusion and Next Steps: Where to go from here.

Let’s dive in and unlock the power of Pantheon from your terminal!

1. What is Terminus and Why Use It?

What is Terminus?

At its core, Terminus is a command-line interface (CLI) application, built with PHP, that interacts with the Pantheon API. Think of it as a remote control for your Pantheon sites and platform services, operated entirely through text commands entered into your computer’s terminal or console. It allows you to perform nearly every action available in the Pantheon Dashboard, plus many more advanced operations, without ever opening a web browser.

Why Use Terminus?

While the Pantheon Dashboard is excellent for visual confirmation and occasional tasks, Terminus offers several compelling advantages, especially as your usage of Pantheon scales or becomes more complex:

  1. Speed and Efficiency: For experienced users, typing a command is often much faster than navigating through multiple web interface screens, clicking buttons, and waiting for pages to load. Tasks like clearing caches, deploying code, or cloning a database can be executed in seconds.
  2. Automation and Scripting: This is arguably the most significant benefit. Terminus commands can be chained together in shell scripts (Bash, Zsh, etc.) to automate complex or repetitive workflows. Imagine a script that automatically:
    • Pulls the latest code from Git.
    • Deploys it to the Dev environment.
    • Clones the Live database and files down to Dev.
    • Runs database updates.
    • Clears caches.
    • Runs automated tests.
      All initiated with a single command! This level of automation is simply not possible with the web UI alone.
  3. Consistency and Reproducibility: Scripts ensure tasks are performed the exact same way every time, reducing the potential for human error that can occur when manually clicking through UI steps. This is crucial for reliable deployment processes.
  4. Integration with Other Tools: As a CLI tool, Terminus integrates seamlessly with other command-line utilities (like git, rsync, curl, jq), local development environments (like Lando or DDEV), and Continuous Integration/Continuous Deployment (CI/CD) systems (like GitHub Actions, GitLab CI, Jenkins, CircleCI).
  5. Access to Deeper Functionality: Some platform operations or information might be more readily accessible or only available via Terminus or the underlying API.
  6. Bulk Operations: Managing multiple sites? Terminus, combined with scripting, allows you to perform actions (like updating core or applying security patches using Drush/WP-CLI commands via Terminus) across numerous sites far more efficiently than doing so manually through the dashboard.
  7. Remote Management: You can manage your Pantheon sites from any machine where Terminus is installed and authenticated, including remote servers or CI environments.

In essence, Terminus empowers you to treat your Pantheon infrastructure as code, enabling more sophisticated, automated, and efficient management practices.

2. Prerequisites

Before you install and start using Terminus, ensure you have the following:

  1. A Pantheon Account: You need an active Pantheon account. If you don’t have one, you can sign up for free on the Pantheon website.
  2. Basic Command-Line Familiarity: You should be comfortable opening a terminal (Terminal on macOS/Linux, Command Prompt, PowerShell, or WSL/Git Bash on Windows) and executing basic commands.
  3. PHP: Terminus is a PHP application. You need PHP installed on your local machine.
    • Version: Check the official Terminus documentation for the currently required PHP versions (typically recent, actively supported versions). You can check your installed version by running php -v.
    • Required Extensions: Terminus usually requires common PHP extensions like curl, json, xml, zip, phar. These are often included in standard PHP installations.
  4. Composer: Composer is the recommended tool for installing and managing PHP dependencies, including Terminus itself. While alternative installation methods exist, Composer provides the easiest way to install and update Terminus.
    • Install Composer globally by following the instructions on the official Composer website. You can verify the installation by running composer --version.
  5. Git (Recommended): While not strictly required for all Terminus commands, Git is fundamental to Pantheon’s workflow. You’ll likely need it installed locally (git --version) for interacting with your site repositories.

Having these prerequisites in place will ensure a smooth installation and usage experience.

3. Installation

There are several ways to install Terminus, but the officially recommended method uses Composer for global installation.

Recommended Method: Composer Global Install

This method installs Terminus as a globally accessible command on your system and makes updating straightforward.

  1. Open your Terminal: Launch your preferred command-line interface.

  2. Run the Composer Command: Execute the following command:

    bash
    composer global require pantheon-systems/terminus

    Composer will download Terminus and its dependencies into a central location (usually ~/.composer/vendor/ or ~/.config/composer/vendor/ on Linux/macOS, and C:\Users\<YourUser>\AppData\Roaming\Composer\vendor\ on Windows).

  3. Ensure the Composer Bin Directory is in your PATH: For your system to find the terminus command, the directory where Composer installs binaries needs to be in your system’s PATH environment variable.

    • macOS/Linux (Bash/Zsh): The directory is typically ~/.composer/vendor/bin or ~/.config/composer/vendor/bin. You need to add a line like this to your shell profile file (~/.bashrc, ~/.bash_profile, ~/.zshrc, etc.):

      “`bash
      export PATH=”$HOME/.composer/vendor/bin:$PATH”

      Or if using the newer default location:

      export PATH=”$HOME/.config/composer/vendor/bin:$PATH”

      ``
      After adding the line, either restart your terminal or run      source ~/.bashrc(or the relevant profile file).
      * **Windows:** The directory is usually      %APPDATA%\Composer\vendor\bin(which translates to something likeC:\Users\\AppData\Roaming\Composer\vendor\bin`). You need to add this directory to your system or user Environment Variables PATH. Search for “Environment Variables” in Windows settings to edit them. You might need to restart your terminal or even log out/log back in for the change to take effect.

  4. Verify Installation: Close and reopen your terminal, then run:

    bash
    terminus --version

    If the installation was successful, you should see the installed Terminus version number printed.

Updating Terminus (Composer Method):

Keeping Terminus updated is crucial for bug fixes and new features. With the Composer global install, updating is simple:

bash
composer global update pantheon-systems/terminus

Alternative Installation Methods (Briefly Mentioned):

While Composer is recommended, other options exist:

  • Phar Archive (.phar): You can download a pre-packaged .phar file from the Terminus releases page on GitHub. You make it executable and can place it anywhere in your PATH. Updates require manually downloading the new .phar file.
  • OS Package Managers: Terminus might be available via package managers like Homebrew (macOS), but these versions might lag behind the official releases. Check their respective repositories for availability and commands (e.g., brew install terminus).

For most users, sticking with the Composer global install provides the best balance of ease of installation and updating.

4. Authentication

Before you can manage your Pantheon sites with Terminus, you need to authenticate – essentially proving to Pantheon who you are. Terminus offers two primary methods: Machine Tokens and OAuth (browser-based login).

Machine Tokens (Highly Recommended)

Machine Tokens are long-lived, unique authentication tokens specifically designed for programmatic access like Terminus, scripts, and CI/CD systems. They are more secure for automated workflows because they don’t require interactive logins and can be easily revoked if compromised.

  1. Generate a Machine Token:

    • Log in to your Pantheon Dashboard in your web browser.
    • Navigate to your Account settings (usually by clicking your profile picture/name).
    • Go to the “Machine Tokens” tab.
    • Click “Create Token”.
    • Give your token a descriptive name (e.g., “My Laptop Terminus”, “GitHub Actions Deploy”).
    • Click “Generate Token”.
    • Important: Copy the generated token immediately and store it securely (like in a password manager). You will not be able to see the token again after closing the confirmation dialog.

  2. Log in with Terminus using the Machine Token:

    • Open your terminal.

    • Run the following command, replacing <your_machine_token> with the token you just generated:

      bash
      terminus auth:login --machine-token=<your_machine_token>

    • Terminus will verify the token with Pantheon and store it locally (usually in ~/.terminus/ or ~/.config/terminus/) for future sessions. You should see a success message.

OAuth (Browser-Based Login)

This method redirects you to your web browser to log in to Pantheon, which then grants Terminus access. It’s simpler for a quick interactive session but less suitable for automation.

  1. Run the Login Command:

    • Open your terminal.

    • Run:

      bash
      terminus auth:login

  2. Follow Browser Instructions:

    • Terminus will likely provide a URL and ask you to open it in your browser, or it might attempt to open it automatically.
    • Log in to your Pantheon account if prompted.
    • Authorize Terminus to access your account.
    • You might be redirected back to a local address or see a confirmation message in the browser. Terminus will detect the successful authentication.

Verifying Authentication

To check which Pantheon user account Terminus is currently authenticated as, run:

bash
terminus auth:whoami

This will display the email address associated with the authenticated account.

Logging Out

If you need to switch accounts or clear your authentication token for security reasons, you can log out:

bash
terminus auth:logout

Security Considerations for Machine Tokens:

  • Treat Machine Tokens like passwords. Do not share them publicly or commit them directly into Git repositories.
  • Use environment variables or secure secret management systems (like HashiCorp Vault, AWS Secrets Manager, GitHub Secrets) to handle tokens in CI/CD environments or shared scripts.
  • Generate specific tokens for specific purposes (e.g., one for your laptop, one for a specific CI job) and revoke them if they are no longer needed or potentially compromised.
  • Give tokens descriptive names in the Pantheon Dashboard so you know what each token is used for.

Using Machine Tokens is the standard and recommended way to authenticate for regular Terminus use and essential for any scripting or automation.

5. Understanding Terminus Command Structure

Terminus follows a consistent command structure, making it predictable and easier to learn once you grasp the basics.

The Basic Format:

terminus <command>:<subcommand> [arguments] [--options]

Let’s break this down:

  • terminus: The executable name itself.
  • <command>:<subcommand>: This specifies the action you want to perform. Terminus organizes commands into logical groups (commands) with specific actions (subcommands).
    • Examples: site:list, env:info, backup:create, drush:status (Note: some commands like drush or wp don’t follow the strict : convention but are top-level commands).
  • [arguments]: These are required or optional pieces of information needed by the command, often identifying the target of the action.
    • <site>: The ID of the Pantheon site you want to interact with. This can be the site’s human-readable name (e.g., my-cool-site) or its UUID.
    • <env>: The specific environment within the site (e.g., dev, test, live, or a Multidev environment name like feature-branch).
    • <site>.<env>: A common shorthand format to specify both the site and environment together (e.g., my-cool-site.dev). Terminus is usually smart enough to parse this.
    • Other arguments might include email addresses (for team commands), file paths, messages, etc., depending on the specific command.
  • [--options]: These modify the command’s behavior. They typically start with double hyphens (--) for full names or a single hyphen (-) for abbreviations.
    • Examples:
      • --message="Your commit message": Provides a commit message.
      • --element=db: Specifies that a backup command should only target the database.
      • --yes or -y: Automatically answers “yes” to confirmation prompts (useful in scripts).
      • --quiet or -q: Suppresses informational output, showing only errors.
      • --verbose or -v, -vv, -vvv: Increases the amount of debug output shown.
      • --format=json: Outputs the command results in JSON format (useful for scripting). Other formats like yaml, list, table are often available.
      • --site=<site>: Explicitly specifies the site ID (alternative to providing it as an argument).
      • --env=<env>: Explicitly specifies the environment name.

Finding Commands and Getting Help

Terminus has built-in help features:

  • List all available commands:

    bash
    terminus list
    This shows all top-level commands and their descriptions.

  • Get help for a specific command:

    “`bash
    terminus help :

    Example:

    terminus help site:list
    terminus help env:deploy
    terminus help backup:create
    “`
    This provides detailed information about the command, including its purpose, required arguments, available options, and often examples. This is your best friend when learning new commands or recalling specific options.

Example Command Breakdown:

Let’s look at a command to deploy code from the dev environment to the test environment for a site named my-awesome-app:

bash
terminus env:deploy my-awesome-app.test --note="Deploying feature X from Dev" --updatedb --cc

  • terminus: The program.
  • env:deploy: The command group (env) and action (deploy).
  • my-awesome-app.test: The argument specifying the target site (my-awesome-app) and environment (test). Terminus infers that the source is the environment below test, which is dev.
  • --note="Deploying feature X from Dev": An option providing a deployment log message.
  • --updatedb: An option to automatically run database updates (like drush updatedb or WP-CLI’s equivalent) after the code deployment.
  • --cc: An option to automatically clear caches after deployment.

Understanding this structure and how to use terminus help is fundamental to effectively using Terminus.

6. Core Terminus Functionality

Now, let’s explore some of the most common and useful Terminus commands, grouped by functionality. Remember to replace placeholders like <site>, <env>, <email>, etc., with your actual values. You can always use terminus help <command> for more details and options.

A. Site Management

These commands help you manage your Pantheon sites themselves.

  • List Your Sites:
    bash
    terminus site:list
    Displays a table of sites you have access to, including name, ID, framework (Drupal/WordPress), owner, etc.

    • Options:
      • --name=<pattern>: Filter by site name (wildcards * supported).
      • --owner=<uuid|email>: Show sites owned by a specific user.
      • --org=<org_uuid|name>: Show sites belonging to a specific organization.
      • --format=list: Output only the site names, one per line (useful for scripting).

  • Get Detailed Site Information:
    bash
    terminus site:info <site>
    # Example:
    terminus site:info my-cool-site
    Shows detailed information about a specific site, including its ID, name, framework, plan, upstream, owner, organization, and more.

  • Manage Site Team Members:

    • List team members:
      bash
      terminus site:team:list <site>
      # Example:
      terminus site:team:list my-cool-site
    • Add a team member:
      bash
      terminus site:team:add <site> <email> <role>
      # Example (roles: developer, team_member, admin):
      terminus site:team:add my-cool-site [email protected] developer
    • Remove a team member:
      bash
      terminus site:team:remove <site> <email>
      # Example:
      terminus site:team:remove my-cool-site [email protected]

  • Create a New Site (Less Common via CLI):
    While possible, site creation often involves selecting an upstream and is frequently done via the dashboard initially.
    bash
    terminus site:create <site_name> <label> <upstream_id> [--org=<org_id>]
    # Example (requires knowing the upstream ID, e.g., empty WordPress):
    # terminus site:create my-new-wp-site "My New WP Site" wordpress-upstream-id --org=my-agency-org
    You can find upstream IDs using terminus upstream:list.

B. Environment Management

These commands focus on the Dev, Test, Live, and Multidev environments within a site.

  • List Environments for a Site:
    bash
    terminus env:list <site>
    # Example:
    terminus env:list my-cool-site
    Shows the environments (Dev, Test, Live, and any Multidevs), their domain names, connection mode (Git/SFTP), and PHP version.

  • Get Detailed Environment Information:
    bash
    terminus env:info <site>.<env>
    # Example:
    terminus env:info my-cool-site.dev
    Displays detailed info about a specific environment, including domain, connection mode, PHP version, Drush version (if applicable), and lock status.

  • Create a Multidev Environment:
    Multidevs are copies of an existing environment (usually Dev or Live) used for feature branches, testing, etc.
    bash
    terminus multidev:create <site>.<source_env> <new_env_name>
    # Example (creates 'feature-x' based on 'dev'):
    terminus multidev:create my-cool-site.dev feature-x
    # Example (creates 'staging' based on 'live'):
    terminus multidev:create my-cool-site.live staging
    This command clones both the codebase and the database/files from the source environment.

  • Delete a Multidev Environment:
    bash
    terminus multidev:delete <site>.<multidev_env> [--delete-branch] [--yes]
    # Example:
    terminus multidev:delete my-cool-site.feature-x --yes

    • --delete-branch: Also deletes the associated Git branch in the site’s repository.
    • --yes: Skips the confirmation prompt (use with caution).
    • Note: You cannot delete Dev, Test, or Live environments.

  • Wipe an Environment:
    Resets an environment (Dev or Multidev) back to the state defined by the site’s chosen upstream, removing all custom code, database content, and files. Use with extreme caution!
    bash
    terminus env:wipe <site>.<env> [--yes]
    # Example (Wipes the 'dev' environment):
    terminus env:wipe my-cool-site.dev --yes

  • Manage Connection Mode (Git vs. SFTP):
    Pantheon environments can be in Git mode (code changes pushed via Git) or SFTP mode (code changes made directly via SFTP, then committed). Dev and Multidevs can be switched; Test and Live are always in Git mode.

    • Set connection mode:
      bash
      terminus connection:set <site>.<env> <git|sftp>
      # Example (Switch dev to SFTP mode):
      terminus connection:set my-cool-site.dev sftp
      # Example (Switch dev back to Git mode):
      terminus connection:set my-cool-site.dev git
    • View connection mode and credentials:
      bash
      terminus connection:info <site>.<env>
      # Example:
      terminus connection:info my-cool-site.dev --field=sftp_command
      This is useful for getting SFTP/SSH connection strings. Use --field=<field_name> to get specific details like sftp_host, sftp_username, sftp_port, or the full sftp_command / ssh_command.

C. Code Management & Deployment

Terminus is central to managing code commits and deployments through the standard Pantheon workflow (Dev -> Test -> Live).

  • Check Code Differences:
    See if there are uncommitted changes (in SFTP mode) or differences between environments.
    bash
    terminus env:diffstat <site>.<env>
    # Example (Show uncommitted changes on Dev in SFTP mode):
    terminus env:diffstat my-cool-site.dev
    # Example (Show code differences between Test and Live):
    terminus env:diffstat my-cool-site.live
    The output is similar to git diff --stat.

  • Commit Changes (SFTP Mode Only):
    If you’ve made changes via SFTP, you need to commit them to the environment’s history before deploying.
    bash
    terminus env:commit <site>.<env> --message="Your commit message" [--force]
    # Example:
    terminus env:commit my-cool-site.dev --message="Update plugin configuration via SFTP"

    • --force: Use if you encounter non-Git files that you want to force-add (use carefully).

  • Deploy Code to an Environment:
    This pulls code changes from the parent environment in the Pantheon workflow (Dev -> Test -> Live).
    bash
    terminus env:deploy <site>.<target_env> [--note="Deployment note"] [--updatedb] [--cc] [--sync-content]
    # Example (Deploy Dev code to Test):
    terminus env:deploy my-cool-site.test --note="Deploy feature Y" --updatedb --cc
    # Example (Deploy Test code to Live):
    terminus env:deploy my-cool-site.live --note="Release version 1.2.0" --updatedb --cc

    • <target_env>: The environment you are deploying to (e.g., test or live).
    • --note: Add a message to the deployment log.
    • --updatedb: Run database updates after code deployment.
    • --cc: Clear caches after deployment.
    • --sync-content: Important: If deploying to test or dev (or a multidev from dev), this option also clones the database and files from the source environment (live when deploying to test, test when deploying to dev). Be very careful using this when deploying to Live, as it’s usually not intended.

  • View Workflow Logs:
    Pantheon operations (deployments, backups, cloning, etc.) run as workflows. You can view their status and logs.

    • List recent workflows for a site:
      bash
      terminus workflow:list <site>
      # Example:
      terminus workflow:list my-cool-site
    • Show detailed log for a specific workflow (get the ID from workflow:list):
      bash
      terminus workflow:log:show <site> <workflow_id>
      # Example:
      terminus workflow:log:show my-cool-site 123e4567-e89b-12d3-a456-426614174000

D. Database Management

Managing database backups and cloning between environments is a critical task.

  • Create a Database Backup:
    bash
    terminus backup:create <site>.<env> [--element=db] [--keep-for=<days>]
    # Example (Backup Dev database):
    terminus backup:create my-cool-site.dev --element=db

    • --element=db: Specifies only the database (omit or use code, files, database for multiple elements). By default, it backs up all three.
    • --keep-for=<days>: Specify retention time in days (overrides default retention).

  • List Database Backups:
    bash
    terminus backup:list <site>.<env> [--element=db]
    # Example:
    terminus backup:list my-cool-site.live --element=db
    Shows available backups, including filename (usually a timestamp) and size.

  • Get Database Backup Download URL:
    bash
    terminus backup:get <site>.<env> --element=db [--to=<file_path>] [--latest]
    # Example (Get URL for the latest Live DB backup):
    terminus backup:get my-cool-site.live --element=db --latest
    # Example (Download the latest Live DB backup to a local file):
    terminus backup:get my-cool-site.live --element=db --latest --to=./live_db_backup.sql.gz
    The command outputs the secure download URL. You can use this with tools like wget or curl, or use the --to option to download directly.

  • Restore a Database Backup:
    Restores a database to the specified environment from a backup file (either a URL or a local path). Use extreme caution, especially on Live! This overwrites the current database.
    bash
    terminus backup:restore <site>.<env> <backup_file_or_url> [--element=db] [--yes]
    # Example (Restore Dev using a backup URL obtained from backup:get):
    terminus backup:restore my-cool-site.dev https://.../backup.sql.gz --element=db --yes
    # Example (Restore Dev using a local backup file):
    terminus backup:restore my-cool-site.dev ./my_local_backup.sql.gz --element=db --yes

  • Clone Database Between Environments:
    A very common task: copying the database from one environment to another (e.g., Live -> Dev, Live -> Test).
    bash
    terminus env:clone-content <site>.<source_env> <target_env> [--db-only] [--cc] [--yes]
    # Example (Clone Live DB to Dev):
    terminus env:clone-content my-cool-site.live dev --db-only --yes
    # Example (Clone Live DB to Test):
    terminus env:clone-content my-cool-site.live test --db-only --yes

    • --db-only: Crucial to specify you only want the database cloned. Otherwise, it clones both database and files.
    • <target_env>: Note that here you only specify the target environment name (e.g., dev), not the full <site>.<env> format. The site is inferred from the source.
    • --cc: Optionally clear caches on the target environment after cloning.

E. Files Management

Similar to databases, managing user-uploaded files (typically in wp-content/uploads or sites/default/files) involves backups and cloning.

  • Create a Files Backup:
    bash
    terminus backup:create <site>.<env> --element=files [--keep-for=<days>]
    # Example (Backup Live files):
    terminus backup:create my-cool-site.live --element=files

  • List Files Backups:
    bash
    terminus backup:list <site>.<env> --element=files
    # Example:
    terminus backup:list my-cool-site.live --element=files

  • Get Files Backup Download URL:
    bash
    terminus backup:get <site>.<env> --element=files [--to=<file_path.tar.gz>] [--latest]
    # Example (Get URL for the latest Live files backup):
    terminus backup:get my-cool-site.live --element=files --latest
    # Example (Download the latest Live files backup):
    terminus backup:get my-cool-site.live --element=files --latest --to=./live_files_backup.tar.gz

  • Restore a Files Backup:
    Restores files to the specified environment from a backup archive. Overwrites existing files in the target environment’s files directory.
    bash
    terminus backup:restore <site>.<env> <backup_file_or_url> [--element=files] [--yes]
    # Example (Restore Dev files using a backup URL):
    terminus backup:restore my-cool-site.dev https://.../backup.tar.gz --element=files --yes

  • Clone Files Between Environments:
    Copying files from one environment to another (e.g., Live -> Dev, Live -> Test).
    bash
    terminus env:clone-content <site>.<source_env> <target_env> [--files-only] [--cc] [--yes]
    # Example (Clone Live files to Dev):
    terminus env:clone-content my-cool-site.live dev --files-only --yes
    # Example (Clone Live files to Test):
    terminus env:clone-content my-cool-site.live test --files-only --yes

    • --files-only: Specify you only want the files cloned.
    • <target_env>: Only the target environment name.

  • Using Rsync/SFTP for Files:
    For syncing individual files or smaller subsets, using rsync or sftp directly might be more efficient than cloning the entire files directory. You can get the necessary connection details using:
    bash
    terminus connection:info <site>.<env> --field=sftp_command
    # Or use ssh and rsync:
    terminus connection:info <site>.<env> --field=ssh_command
    # Example using rsync (after getting SSH details):
    # rsync -rLvz --size-only --ipv4 --progress -e 'ssh -p <port>' <local_path>/ <user>@<host>:files/
    Refer to Pantheon’s documentation for detailed rsync examples.

F. Executing Remote Commands (Drush & WP-CLI)

One of Terminus’s most powerful features is the ability to execute Drush (for Drupal) and WP-CLI (for WordPress) commands directly on a Pantheon environment without needing to SSH in manually.

  • Syntax: The key is to place the Drush/WP-CLI command and its arguments after a double hyphen (--).

  • Executing Drush Commands:
    bash
    terminus drush <site>.<env> -- <drush_command> [drush_options_and_args]

    • Clear Drupal caches:
      bash
      terminus drush my-drupal-site.dev -- cache-rebuild
      # Or the alias:
      terminus drush my-drupal-site.dev -- cr
    • Run database updates:
      bash
      terminus drush my-drupal-site.dev -- updatedb -y
    • Get a one-time login link:
      bash
      terminus drush my-drupal-site.dev -- user-login
      # Or for a specific user:
      terminus drush my-drupal-site.dev -- uli admin
    • Export configuration (Drupal 8+):
      bash
      terminus drush my-drupal-site.dev -- config:export -y
      # Note: This exports within the container; combine with Git/SFTP to retrieve.
    • List enabled modules:
      bash
      terminus drush my-drupal-site.dev -- pm:list --status=enabled

  • Executing WP-CLI Commands:
    bash
    terminus wp <site>.<env> -- <wp_cli_command> [wp_cli_options_and_args]

    • Get WordPress core version:
      bash
      terminus wp my-wp-site.dev -- core version
    • List installed plugins:
      bash
      terminus wp my-wp-site.dev -- plugin list
    • Activate a plugin:
      bash
      terminus wp my-wp-site.dev -- plugin activate my-plugin
    • Run database updates (often needed after core/plugin updates):
      bash
      terminus wp my-wp-site.dev -- core update-db
    • Flush rewrite rules:
      bash
      terminus wp my-wp-site.dev -- rewrite flush
    • Clear object cache (if using Redis/Memcached via Pantheon):
      bash
      terminus wp my-wp-site.dev -- cache flush
    • Search and replace in the database (use with caution!):
      bash
      # Example: Replace http://oldsite.com with https://newsite.com
      terminus wp my-wp-site.dev -- search-replace 'http://oldsite.com' 'https://newsite.com' --all-tables --report-changed-only

Important Note on --: The double hyphen -- is crucial. It tells Terminus “everything after this point should be passed directly to the remote Drush/WP-CLI command.” Without it, Terminus might try to interpret the Drush/WP-CLI options as its own options.

Being able to run these commands remotely via Terminus is fundamental for deployment scripts, maintenance tasks, and quick administrative actions.

7. Workflow Automation & Scripting

The true power of Terminus shines when you combine commands into scripts to automate common workflows. Shell scripts (like Bash) are perfect for this.

Example 1: Simple Deployment and Cache Clear Script (Dev to Test)

Let’s create a script deploy_dev_to_test.sh for deploying code from Dev to Test, running DB updates, and clearing caches.

“`bash

!/bin/bash

Configuration

SITE_ID=”my-cool-site”
DEPLOY_NOTE=”Automated deployment from Dev by script”

Ensure script exits if any command fails

set -e

echo “Starting deployment for site: $SITE_ID”

Deploy code from Dev to Test

echo “Deploying code to Test environment…”
terminus env:deploy “$SITE_ID.test” –note=”$DEPLOY_NOTE” –updatedb –cc –yes

echo “Deployment workflow initiated successfully.”
echo “Monitor progress in the Pantheon Dashboard or via ‘terminus workflow:list $SITE_ID'”

Optional: Wait for deployment workflow to finish (more advanced)

You could poll terminus workflow:list or use a plugin with wait commands.

echo “Deployment script finished.”
exit 0
“`

  • Make the script executable: chmod +x deploy_dev_to_test.sh
  • Run it: ./deploy_dev_to_test.sh

Example 2: Refreshing Dev Environment from Live

A common task is updating the Dev environment with the latest content from Live. Script refresh_dev_from_live.sh:

“`bash

!/bin/bash

Configuration

SITE_ID=”my-cool-site”

Ensure script exits if any command fails

set -e

echo “Refreshing Dev environment for site: $SITE_ID from Live…”

Clone Database from Live to Dev

echo “Cloning database from Live to Dev…”
terminus env:clone-content “$SITE_ID.live” dev –db-only –yes

Clone Files from Live to Dev

echo “Cloning files from Live to Dev…”
terminus env:clone-content “$SITE_ID.live” dev –files-only –yes

Optional: Clear caches on Dev after cloning

echo “Clearing caches on Dev…”
terminus drush “$SITE_ID.dev” — cr || terminus wp “$SITE_ID.dev” — cache flush

echo “Dev environment refresh complete.”
exit 0
“`

Using Machine-Readable Output:

For more complex scripting, you often need to capture output from one command to use in another. The --format option is key here.

  • --format=list: Outputs a simple list, often just IDs or names, one per line. Good for looping.
  • --format=json: Outputs detailed information in JSON format. Use tools like jq to parse this.
  • --format=yaml: Similar to JSON but in YAML format.
  • --field=<field_name>: Directly outputs the value of a single field.

Example: Scripting Backups Across Multiple Sites

“`bash

!/bin/bash

List of site IDs or names to back up

SITES=(
“site-alpha”
“site-beta”
“client-site-gamma”
)

Element to back up (db, files, code, or leave empty for all)

BACKUP_ELEMENT=”db” # Change as needed

echo “Starting backup process…”

for SITE in “${SITES[@]}”; do
echo “————————————”
echo “Processing site: $SITE”

# Trigger backup creation for Live environment
echo ” Triggering $BACKUP_ELEMENT backup for $SITE.live…”
terminus backup:create “$SITE.live” –element=”$BACKUP_ELEMENT”

# Optional: Get the download URL for the latest backup
# echo ” Getting latest backup URL…”
# BACKUP_URL=$(terminus backup:get “$SITE.live” –element=”$BACKUP_ELEMENT” –latest)
# if [ $? -eq 0 ] && [ -n “$BACKUP_URL” ]; then
# echo ” Latest backup URL: $BACKUP_URL”
# # You could add commands here to download the backup using wget/curl
# else
# echo ” Could not retrieve backup URL.”
# fi

echo ” Backup initiated for $SITE.live.”
done

echo “————————————”
echo “Backup process finished.”
exit 0
“`

These examples only scratch the surface. You can build sophisticated scripts for updates, testing, content staging, and integration with CI/CD pipelines using Terminus as the bridge to your Pantheon environments.

8. Advanced Topics & Best Practices

As you become more proficient with Terminus, consider these advanced topics and best practices:

A. Terminus Aliases for Local Drush/WP-CLI

Terminus can generate alias files that allow your local installation of Drush or WP-CLI to interact with your Pantheon sites directly, without needing the terminus drush or terminus wp wrappers for every command.

  • Generate Aliases:
    bash
    terminus aliases
    Follow the instructions provided by the command. It will typically tell you where it saved the alias file (e.g., ~/.drush/pantheon.aliases.drushrc.php for Drush, ~/.wp-cli/config.yml additions for WP-CLI).

  • Usage: Once configured, you can use aliases like @pantheon.sitename.env.
    “`bash
    # Drush example: Clear cache on Dev environment of my-site
    drush @pantheon.my-site.dev cr

    WP-CLI example: List plugins on Live environment of my-wp-site

    wp @pantheon.my-wp-site.live plugin list
    “`
    This can feel more natural if you’re already heavily using local Drush/WP-CLI.

B. Terminus Plugins

Terminus has a plugin architecture that allows developers to extend its functionality with custom commands. Many useful plugins are available from Pantheon and the community.

  • Finding Plugins: Check the Pantheon Terminus Plugins documentation and community lists.
  • Listing Installed Plugins:
    bash
    terminus plugin:list
  • Installing a Plugin (using Composer):
    Plugins are typically Composer packages.
    bash
    terminus self:plugin:install <vendor/package-name>
    # Example: Install the Build Tools plugin (common for CI workflows)
    terminus self:plugin:install pantheon-systems/terminus-build-tools-plugin
  • Updating Plugins:
    bash
    terminus self:plugin:update <vendor/package-name>
    # Or update all installed plugins:
    terminus self:plugin:update --all
  • Uninstalling a Plugin:
    bash
    terminus self:plugin:uninstall <vendor/package-name>
    Plugins can add commands for tasks like interacting with specific Pantheon services (e.g., Solr, Redis), managing secrets, waiting for workflows, running complex build steps, and much more. The terminus-build-tools-plugin is particularly useful for CI/CD integrations.

C. Configuration via Environment Variables

For non-interactive use (scripts, CI/CD), you can configure Terminus using environment variables instead of relying on stored tokens or interactive prompts.

  • TERMINUS_TOKEN: Set this to your Pantheon Machine Token.
    bash
    export TERMINUS_TOKEN="<your_machine_token>"
    terminus site:list # Will use the token from the environment variable
  • TERMINUS_SITE: Set a default site ID/name. Commands will use this site unless overridden by an argument or --site option.
    bash
    export TERMINUS_SITE="my-default-site"
    terminus env:list # Will list environments for 'my-default-site'
    terminus env:list other-site # Still works by providing the argument
  • TERMINUS_ENV: Set a default environment name.
    bash
    export TERMINUS_ENV="dev"
    export TERMINUS_SITE="my-site"
    terminus drush -- cr # Will clear cache on my-site.dev
  • TERMINUS_HIDE_UPDATE_MESSAGE=1: Suppress the “Terminus update available” message.

Using environment variables is crucial for security and flexibility in automated environments.

D. Best Practices

  • Use Machine Tokens: Prefer Machine Tokens over OAuth for all regular use, especially scripting.
  • Protect Your Tokens: Treat tokens like passwords. Use environment variables or secret management tools in CI/CD. Avoid committing them to code.
  • Be Cautious with Destructive Commands: Commands like env:wipe, backup:restore, multidev:delete, and env:clone-content (especially to Live) can cause data loss if misused. Always double-check the target environment and use the --yes option sparingly, primarily in well-tested scripts.
  • Use --yes in Scripts: In automated scripts where prompts would halt execution, use -y or --yes on commands that require confirmation (after careful consideration!).
  • Leverage terminus help: Don’t guess command syntax or options. Use the built-in help.
  • Keep Terminus Updated: Regularly run composer global update pantheon-systems/terminus (or your chosen update method) to get bug fixes and new features.
  • Specify Site and Environment Clearly: While Terminus can sometimes infer these, explicitly providing <site>.<env> or using --site and --env makes commands less ambiguous, especially in scripts.
  • Use --quiet in Scripts: For automated scripts where you only care about success/failure or specific output, use -q to reduce noise.
  • Use --format=json or list for Scripting: Rely on machine-readable output formats when piping command results or parsing them in scripts. Avoid parsing human-readable table output, which can change between versions.
  • Monitor Workflows: Long-running operations (deploy, clone, backup) run as background workflows. Use terminus workflow:list and terminus workflow:log:show to check their status and troubleshoot failures. Consider plugins like terminus-build-tools-plugin which often include workflow:wait commands for scripts.

9. Troubleshooting Common Issues

Even with a powerful tool like Terminus, you might encounter issues. Here are some common problems and how to approach them:

  • terminus: command not found:
    • Cause: Terminus is not installed correctly, or the Composer bin directory is not in your system’s PATH.
    • Solution: Revisit the Installation section. Ensure Composer is installed, run composer global require pantheon-systems/terminus, and verify that the correct directory (~/.composer/vendor/bin or similar) is correctly added to your PATH and that your shell has loaded the updated PATH (try restarting the terminal).
  • Authentication Errors (e.g., Permission denied, Could not find machine token):
    • Cause: Invalid or missing Machine Token, expired OAuth session, or incorrect token used.
    • Solution:
      1. Run terminus auth:whoami to see if you are logged in correctly.
      2. If using Machine Tokens, ensure the token is valid (not revoked) and correctly provided via terminus auth:login --machine-token=... or the TERMINUS_TOKEN environment variable. Double-check for typos.
      3. If using OAuth, try logging out (terminus auth:logout) and logging back in (terminus auth:login).
      4. Ensure the user associated with the token has the necessary permissions on the target site/environment in the Pantheon Dashboard.
  • Permission Denied for Specific Actions (e.g., deploying to Live):
    • Cause: The authenticated Pantheon user does not have the required role (e.g., Team Member, Admin) on the site or organization to perform the action.
    • Solution: Check the user’s role in the Pantheon Dashboard team management section for the site. You may need someone with Admin privileges to grant the necessary permissions.
  • Command Timeout Errors:
    • Cause: Long-running operations (like large database clones or complex Drush/WP-CLI commands) might exceed default timeout limits. Network issues can also contribute.
    • Solution:
      1. Check your internet connection.
      2. Some Terminus commands might have timeout options, or you might need to adjust PHP’s max_execution_time setting in your local php.ini if the timeout occurs locally (less common for Terminus itself).
      3. For long-running Pantheon workflows (deploy, clone), they run in the background. The Terminus command initiates them; you can check progress with terminus workflow:list. Don’t assume the command failed just because the terminal returned before the dashboard showed completion.
  • Drush/WP-CLI Command Errors:
    • Cause: Syntax errors in the command passed after --, issues with the site’s code (e.g., PHP errors), database connectivity problems within the container, or incompatible plugin/module versions.
    • Solution:
      1. Double-check the Drush/WP-CLI command syntax.
      2. Try running the command with increased verbosity: terminus drush <site>.<env> -- -v <command> or terminus wp <site>.<env> -- --debug <command>.
      3. Check the site’s logs (e.g., Drupal watchdog, PHP error logs) in the Pantheon Dashboard.
      4. Ensure the site’s codebase is functional in the target environment.
  • “Could not find site” or “Could not find environment” errors:
    • Cause: Typo in the site name or environment name, or the authenticated user doesn’t have access to that specific site/environment.
    • Solution: Verify the site/environment name using terminus site:list and terminus env:list <site>. Check your permissions in the Pantheon Dashboard.

Getting More Help:

  • Verbose Output: Run the failing Terminus command with -v, -vv, or -vvv for increasingly detailed debug output. This can often pinpoint the problem.
    bash
    terminus -vvv site:list
  • Official Documentation: The Pantheon Terminus Documentation is the definitive resource.
  • terminus help: As mentioned before, use terminus help <command> extensively.
  • Pantheon Community: Ask questions in the Pantheon Community Forum or the Pantheon Slack (#terminus channel).
  • GitHub Issues: If you suspect a bug in Terminus itself, search for or report it on the Terminus GitHub repository issues page.

10. Conclusion and Next Steps

Terminus is more than just a convenience; it’s a fundamental tool for professional Pantheon users. By providing command-line access to the platform’s capabilities, it unlocks significant gains in speed, efficiency, automation, and integration possibilities. From simple cache clears and deployments to complex scripted workflows spanning multiple sites and integrating with CI/CD pipelines, Terminus empowers you to manage your Pantheon infrastructure effectively and reliably.

We’ve covered the essential ground: understanding what Terminus is, installation, authentication, command structure, core functionalities for managing sites, environments, code, databases, and files, executing remote commands, and the basics of scripting and best practices.

Where to go from here?

  1. Practice: The best way to learn Terminus is to use it. Start integrating it into your daily workflow for tasks you currently perform via the dashboard. Try cloning content, deploying code, and clearing caches from your terminal.
  2. Explore terminus help: Pick a command group (like backup or multidev) and explore its subcommands and options using terminus help.
  3. Write Simple Scripts: Identify a repetitive task (like refreshing your Dev environment) and try scripting it using the examples provided as a starting point.
  4. Investigate Plugins: Explore available Terminus plugins, especially terminus-build-tools-plugin if you’re interested in CI/CD.
  5. Integrate with CI/CD: If you use tools like GitHub Actions, GitLab CI, Jenkins, etc., learn how to install and authenticate Terminus within those environments to automate your build, test, and deployment processes.
  6. Consult the Documentation: Keep the official Pantheon Terminus documentation handy as your primary reference.

Mastering Terminus takes time and practice, but the investment pays off significantly in streamlined workflows, reduced errors, and the ability to implement sophisticated automation. Embrace the command line, and unlock the full potential of the Pantheon platform. Happy scripting!

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top