Install and Update Terminus

This page provides information on how to install, authenticate, and update Terminus.

Compatibility and Requirements

Terminus has been tested on the following platforms:

• MacOS
• Windows 10 (WSL 2 Ubuntu 20.0+)
• Ubuntu 20.0 (Including Ubuntu under Docker or VirtualBox)

Terminus requires the following:

• PHP Version 7.4 or later
  • You can check your PHP version by running php -v from a terminal application.
  • You must have the php-xml extension for:
    • mbstring
    • XML
    • cURL
    • CLI
• Composer
• Git
  • This may be needed for the plugin manager component.
• OpenSSH 7.8 or later
  • You can check your OpenSSH version by running ssh -V from a terminal application.
  • This package is required for executing nested Drush or WP-CLI commands.

Installation and Update Methods

MacOS

Homebrew, a package manager for MacOS, is the recommended installation method for MacOS. However, the method described below for Windows and Linux can also be used by MacOS users who are not using Homebrew.

Install Terminus by running the command below:

brew install pantheon-systems/external/terminus

Update to the newest version of the Homebrew installation by running the command below:

brew upgrade terminus

Windows and Linux

Installing Terminus with a PHAR (a stand-alone executable PHP archive) is recommended for Linux and Windows users. This technique is also viable for MacOS users who prefer not to use Homebrew.

The commands below will:

• Create a terminus folder in your home directory (~/)
• Get the latest release tag of Terminus
• Download and save the release as ~/terminus/terminus
• Make the file executable
• Add a symlink to your local bin directory for the Terminus executable

mkdir -p ~/terminus && cd ~/terminus
curl -L https://github.com/pantheon-systems/terminus/releases/download/3.6.1/terminus.phar --output terminus
chmod +x terminus
./terminus self:update
sudo ln -s ~/terminus/terminus /usr/local/bin/terminus

Update the standalone Terminus PHAR installation to the newest version by running the command below:

terminus self:update

Authentication

Login via Machine Token (Required)

You must log in with a machine token after the installation completes. A machine token is used to securely authenticate your machine. Machine tokens provide the same access as your username and password, and do not expire. Refer to Machine Tokens for more information.

1. Go to your Personal Settings, select Machine Tokens, then Generate a Machine Token.

2. Use your machine token to authenticate into Terminus, replacing <[email protected]> and <machine_token>:

   terminus auth:login --email=<[email protected]> --machine-token=<machine_token>

Machine tokens are keyed to the email address associated with your Pantheon user account. Future sessions are authenticated with your email address after a token has been used to authenticate Terminus:

terminus auth:login --email <[email protected]>

SSH Authentication (Optional, but recommended)

Commands that execute remote instructions to tools like Drush or WP-CLI require SSH authentication. Refer to Generate and Add SSH Keys to prevent password requests when executing these commands.