Terminus is Pantheon's Command Line Interface (CLI), providing at least equivalent functionality to the Pantheon's browser-based Dashboard and easier scripting.
If you would like to contribute, pull requests are welcome!
Our documentation is kept in the Terminus Manual, located here: https://pantheon.io/docs/terminus
- A command-line client
- PHP version 5.6.40 or later recommended (5.5.38 minimum)
- PHP-CLI
- PHP-CURL
- PHP-XML
- PHP-JSON
Once you have at least the requirements installed, you can install Terminus via Composer or Git. Additionally, you may want to install the optional software below to enhance your use of Terminus:
- Composer
- Drush (Useful to run incompatible-with-Terminus Drush commands)
- WP-CLI (Useful to run incompatible-with-Terminus WP-CLI commands)
- 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.
There are several ways to install Terminus, depending on your use case:
- For a composer-managed version of Terminus that is not part of your other composer-managed project(s) and doesn't utilize global composer installations, use the Terminus installer.
- If you want to contribute to the Terminus project, download and install from the git repository.
- To add Terminus as a dependency of your composer-based project, install with Composer.
- For a self-contained Terminus executable, install terminus.phar.
-
Download the latest
terminus.phar
from the Releases page. In the example below, we're directing the file to$HOME/bin/
and renaming the file toterminus
:wget https://github.com/pantheon-systems/terminus/releases/latest/download/terminus.phar -O ~/bin/terminus
This will grab the latest version of Terminus from the Releases page.
-
Make the Terminus file exectable. The example below assumes the same installation path as above:
chmod +X ~/bin/terminus
Note: Your installation directory must be in or added to your $PATH
environment variable in order to call terminus
from any working directory.
Run this in your Terminal client:
curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar && php installer.phar install
For more information on installation options or to report an issue with this method, please see the Terminus Installer README.md file.
Note: Terminus installed this way cannot use terminus update
to self-update versions.
Run this in your terminal client:
cd /install/location ; composer require pantheon-systems/terminus
If you are having issues installing, please see to it that any old versions of Terminus are removed by using
composer remove pantheon-systems/terminus
before requiring it.
Do not install Terminus via composer global require
. composer global require
should not be used to install php applications. If you need to globally install something using composer
, use the cgr
utility as a replacement instead.
Note: Terminus installed this way cannot use terminus update
to self-update versions.
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
- Install the Composer dependencies:
cd terminus ; composer install
You can now run the bleeding-edge version of Terminus via:
bin/terminus
Note: Terminus installed this way cannot use terminus update
to self-update versions.
Run this in your Terminal client:
curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar && php installer.phar update
For more information on update options or to report an issue with this method, please see the Terminus Installer README.md file.
Run this in your terminal client:
cd /install/location ; composer update
Updating with Homebrew (for Macs)
Update Terminus with this command:
brew upgrade homebrew/php/terminus
To update with Git and use Terminus HEAD, you should update this repository and then update its dependencies via Composer.
- Update the repository:
cd /install/location/terminus ; git pull
- Update the Composer dependencies:
composer update
Optionally, for ease of development we suggest aliasing, setting the PATH in the bash configuration file, or
symlinking to it. This file is located at ~/.bashrc
on Linux systems and at ~/.bash_profile
on Mac.
alias terminus="/install/location/terminus/bin/terminus"
Once you source the file or restart your terminal client, you can now make use of Terminus using
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
Adding a symlink to /install/location/terminus/bin/terminus
inside your bin directory will work.
To get started with Terminus, you must first authenticate:
terminus auth:login --machine-token=xxxxxxxx
[notice] Logging in via machine token
If you are planning to run WP-CLI or Drush commands through Terminus, please upload an SSH key for the user that will be executing Terminus.
Commands in Terminus follow a predictable pattern:
terminus command:subcommand:subcommand param param --option=value --option
terminus
is the name of the application.command[:subcommand[:subcommand]]
is the name of the command to run. Terminus commands may consist of only acommand
.param
are parameters, and are almost always required for operating the command.option
are options, and are never required to run a command. They may or may not require a value.
Terminus can use certain environment variables to set certain default values when invoking commands. Check the
config/constants.yml
file for the names of variables which can be set. Do not alter this file - add global settings to
your ~/.terminus/config.yml
file or export them in your terminal client.
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.
- Terminus will not offer you options for selection when parameters are not provided. This will be added in the future.
- See the CONTRIBUTING document.
- Create an issue on this repository to discuss the change you propose should be made.
- Fork this repository.
- Clone the forked repository.
- Run
composer install
at the repository root directory to install all necessary dependencies. - Make changes to the code.
- Run the test suite. The tests must pass before any code will be accepted.
- Commit your changes and push them up to your fork.
- Open a pull request on this repository to merge your fork.
Your pull request will be reviewed by Pantheon and changes may be requested before the code is accepted.
Tests are run via the .scripts/test.sh
script. Components thereof can be run as follows:
composer cs
runs the code sniffer to ensure all code is appropriately formatted.composer phpunit
runs the PHPUnit unit tests.composer behat
runs the Behat feature tests
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:
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 self:info
. - The output of the issue in debug mode. (Run the command with
--vvv
appended to it.)
- 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.
Head over to your support tickets in the Pantheon Dashboard and submit a new issue ticket. Please include the helpful information you have gathered.
Dependencies are easily updated by Composer. To update this codebase:
- Check Gemnasium (see the button under the status heading above) to see if there are dependencies requiring an update.
- Check out a new branch off of an up-to-date copy of master.
- Run
composer update
at the repository root directory. - Run the test suite. If there are errors, address them.
- Commit the changes, push the branch, and create a pull request for the update.
To deploy a new version of Terminus:
- Ensure that the version numbers atop
CHANGELOG.md
and inconfig/constants.yml
are updated to the new version. - Create a release in GitHub.
- Copy all
CHANGELOG.md
entries for the new version into the description of the release. - Tag the new release with its version number.
- Release it. It will become automatically available to the public via Packagist and the Terminus Installer.
- Run Terminus with the
-vvv
option to get debug output. - If you are getting
PHP Fatal error: Uncaught exception 'ReflectionException' ...
, install php-xml. - If you are getting
cURL error 60: SSL certificate problem: ...
, download a cacert.pem file and addcurl.cainfo = "[path_to_file]\cacert.pem"
to yourphp.ini
. If using XAMPP, you can add this to yourxampp\php\extras\ssl
directory.
- The code must be PSR-2 formatted.
- The files must be appropriately namespaced so they are automatically found.
- All new lines must be unit tested with PHPUnit. Ideally, all lines should be reached at least once while running the unit testing suite.
- Functions should be as simple as possible so as to not require a great number of tests per function.
- All reasonable states of any given command should have a Behat feature test. If fixing for a scenario not previously imagined or once considered unreasonable also test it.
- Add changes to
CHANGELOG.md
and include the pull request number. (You will have to push a second time once you have one.) - All functions get comment markup consisting of at least all parameters, returned values, and exceptions thrown. An explanation should be included if it is not apparent.
- Explain why you did what you did in the commit messages.
- Pantheors: Add your Jira ticket number if it is available.