Terminus

Terminus is Pantheon's Command Line Interface (CLI), providing equivalent functionality to the Pantheon Web Dashboard and easier scripting.

If you would like to contribute, pull requests are welcome!

Installation

Requirements:

PHP version 5.5.9 or later
PHP-CLI
PHP-CURL

Once you have at least the requirements installed, you can install Terminus via Composer, cURL, or Git. Additionally, you may want to install the optional software below to enhance your use of Terminus:

Optional but recommended:

Drush (Useful to run incompatible-with-Terminus Drush commands)
WP-CLI (Useful to run incompatible-with-Terminus WP-CLI commands)
Composer
Git

You can install Terminus just about anywhere on your system. In this README, we'll use /install/location to stand in for your chosen installation location.

####Installing with Composer

The fastest and easiest way to install Terminus is via Composer. Simply run this in your terminal client:

composer require pantheon-systems/terminus

####Installing with cURL

Run this in this in your terminal client:

curl https://github.com/pantheon-systems/terminus/releases/download/0.11.2/terminus.phar -L -o /usr/local/bin/terminus && chmod +x /usr/local/bin/terminus

####Installing with Homebrew(for Macs)

If you do not have homebrew-php already tapped, here are the commands for the taps:

brew tap homebrew/dupes
brew tap homebrew/versions
brew tap homebrew/php

And after you're all tapped out, install Terminus with this command:

brew install homebrew/php/terminus

####Installing with Git To install with Git and use Terminus HEAD, you should clone this repository and run Terminus directly. If you would like to contribute to the Terminus source, this is the way you should install it. You will require Composer for this installation.

Clone the repository. If you plan on contributing to the project, create a fork and clone the fork instead.

cd /install/location
git clone https://github.com/pantheon-systems/terminus.git terminus

Or replace /install/location with the directory to which you would like to install.

Install the Composer dependencies.

cd terminus
composer install

You can now run the bleeding-edge version of Terminus via:

bin/terminus

Optionally, for ease of development, we suggest aliasing or setting the path to this script in your Bash configuration file. This file is located at ~/.bashrc on Linux and ~/.bash_profile on Mac.

alias terminus="/install/location/terminus/bin/terminus"

export PATH="$PATH:/install/location/terminus/bin"

Once you source the file or restart your terminal client, you can now make use of Terminus using

terminus

Authentication

To get started with Terminus, you must first authenticate:

terminus auth login
Your email address?: user@pantheon.io
Your dashboard password (input will not be shown)
[1969-07-20 20:18:00] [info] Logging in as user@pantheon.io
[1969-07-21 02:56:00] [info] Saving session data

Tab completion

Terminus also comes with a tab completion script for Bash. Just download terminus-completion.bash and source it from ~/.bash_profile:

source /FULL/PATH/TO/terminus-completion.bash

(Don’t forget to run source ~/.bash_profile afterwards)

Setting default user, site, environment, etc. and Dotenv

Terminus can use certain environment variables to set certain default values when invoking commands. For example, by exporting the environment variable TERMINUS_SITE=<sitename> Terminus will automatically dispatch all commands against that site allowing you to omit the --site=<sitename> in your commands. A list of available environment variables is listed in the .env-sample file.

Terminus also has built-in support for PHP Dotenv, which provides an alternative to manually exporting environment variables. This involves defining environment variables within a .env file that Terminus will automatically use when invoked within that working directory.

Support

Please make ready the steps to reproduce the issue, outputs, pertinent information about your system, and what you believe the correct reaction of the system ought to be. Reporting of issues encountered should happen in one of two ways:

Information that helps us help you:

If we cannot duplicate an issue, we cannot resolve it. Giving us as much information about the problem you're having as you can will help reduce the amount of time between an issue's being reported and being resolved. This is typically the most helpful information:

The result of running terminus cli info.
The output of the issue in debug mode. (Run the command with --debug appended to it.)
The name and version of the OS you're seeing the issue on.

If yours is a problem with Terminus itself:

Search Terminus' issues on GitHub to see whether another user has reported the same issue you are experiencing.
If the problem you are experiencing is not in the issues, you can open a new issue. Please include the helpful information you have gathered.
If you find your problem in an issue, feel free to add your issue information in the comments and/or subscribe to the issue's notifications.

If the problem is with the Pantheon platform:

Head over to your support tickets in the Pantheon Dashboard and submit a new issue ticket. Please include the helpful information you have gathered.

Contributions

Here are steps to follow if you would like to contribute to Terminus:

Fork the repository.
Add your changes. Please add tests as necessary. You can check your syntax for coherence to our standards by running:

cd /install/location/terminus
./scripts/lint.sh

And run your tests via:

cd /install/location/terminus
./scripts/test.sh

Please also run the internal documentation generator before committing your changes. This keeps the documentation always up-to-date:

cd /install/location/terminus
php utils/make-docs.php

Open a pull request on GitHub so that we may evaluate and merge your changes.

Credits

We have leaned heavily on the work of WP-CLI in architecting this command line utility with an object-oriented structure.
We've also (obviously) been greatly inspired by Drush.

gormus/terminus