Skip to main content
Log inGet free account

Install and Update Terminus

Learn how to install and update Terminus to your local computer.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

This section provides information on how to install and authenticate Terminus.

Refer to Current Terminus Release, Changelog, and Updates if you are looking for instructions on how to update Terminus for your specific operating system.

Terminus is available for MacOS and Linux. Windows 10 users can install the Windows Subsystem for Linux, and then install Terminus in the Linux shell.

Some Terminus commands use SSH authentication. You may want to generate and add SSH keys to your account before you continue.

Compatible Operating Systems

Terminus has been tested on the following platforms:

  • MacOS
  • Windows 10 – WSL 2 Ubuntu 20.0
  • Ubuntu 20.0 – this would include Ubuntu under Docker or VirtualBox

Incompatible Operating Systems

Terminus does not work with the following platforms:

  • Windows 10 – Command Line
  • Windows 10 – Git Bash (MingW)
  • Ubuntu 18.0 and earlier versions
  • Linux system with coreutils equal to or less than 8.28

Terminus Requirements

Package Manager

Ubuntu/WinWSL-Ubuntu

MacOS

Required Packages

  • 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:
  • 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.

Install Terminus

There are several ways to install Terminus, depending on your use case:

Standalone Terminus PHAR

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

MacOS Homebrew Installation

The Terminus application is published to Homebrew.

Run the command below to install Terminus:

brew install pantheon-systems/external/terminus

Ubuntu/WinWSL-Ubuntu Installation

Follow the steps in the Standalone Terminus PHAR section.

Authenticate

Machine Token

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

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.

Update Standalone Terminus

You can update the standalone Terminus PHAR installation to the newest version with the command below.

Warning

The self:update command is only available for the standalone Terminus installation. Refer to the command documentation for available options.

terminus self:update

Update Terminus Installer PHAR

You can update the Composer-managed version of Terminus that was installed with the Terminus Installer PHAR.

  1. Navigate to the directory where Terminus was originally installed.

  2. Run the following command:

    curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar && php installer.phar update

Update Terminus Homebrew Installation

You can update to the newest version of the Homebrew installation by running the command below:

brew upgrade pantheon-systems/external/terminus
Note

Terminus uses Semantic versioning. Be sure to fully test compatibility with existing configurations before upgrading to new major releases.

Update Terminus with Plugin

Use the self:plugin:update command if you use the Terminus plugin manager.

Troubleshooting

Nothing to install or update

For Composer-managed Terminus installations, if the update command above returns an output that indicates no updates were found:

  1. Delete the existing Terminus version (e.g. $HOME/terminus).

  2. Re-run the install command:

    rm -rf $HOME/terminus
mkdir $HOME/terminus
cd $HOME/terminus
curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar
php installer.phar install

Self:update not defined

The self:update command is only available for standalone Terminus installed using the standalone Terminus PHAR. If self:update returns a not defined error, use the Terminus Installer PHAR update instructions above.

More Resources