Many developers feel more at home using the command line than they do using a GUI. Edit a text file, issue a command, and bang—you've completed your task. There's just something about doing it all from the command line that makes it a little more exciting. Until recently, WordPress didn't have a great answer for developers who are most at home on the CLI.
WP-CLI is a tool used to manage a WordPress installation. However, don't think of it as a simple backup or search and replace tool. Yes, it can do those things, but it's so much more than that. This guide will walk you through creating and configuring a site from the command line using Pantheon's own CLI, called Terminus, which allows you to call WP-CLI remotely without using a local installation.
Be sure that you:
- Are familiar with your operating system's command line.
- Are using a Unix-based system (Linux or Mac OS X). Windows commands may vary slightly.
- Have created a Pantheon account. Pantheon accounts are always free for development.
Terminus provides advanced interaction with the platform and allows us to run WP-CLI commands remotely. Terminus also opens the door to automating parts of your workflow by combining multiple operations. For more information about Terminus itself, see our Terminus Manual.
Install Terminus within the
mkdir $HOME/terminus cd $HOME/terminus curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar && php installer.phar install
Generate a Machine Token from within User Dashboard > Account > Machine Tokens. Then use it to authenticate Terminus:
terminus auth:login --machine-token=‹machine-token›
For details, see Terminus Manual: Install.
Once installed, verify your session:
If you see your Pantheon sites, then it was installed and authenticated successfully! Once you are comfortable with Terminus, you may find it faster to use than the browser.
The next few secions of this guide use the example variables
"Terminus Demo Site" as the site name and label. Make sure to replace each instance, as well as other variables like the site URL and user/password combinations, with your desired values.
Create a new WordPress site on Pantheon:
terminus site:create tessa-site-wp "Terminus Demo Site" WordPress
If you would like to associate this site with an Organization, you can add the
--orgoption to the command above and pass the Organization name, label, or ID. To associate an existing site with an Organization, use the
Open your new Site Dashboard in a browser:
terminus dashboard:view tessa-site-wp
Keep this window open while you continue reading so you can see the changes you are making in Terminus almost immediately in your Site Dashboard.
Get the platform domain for the Dev environment:
terminus env:info tessa-site-wp.dev --field=domain
You'll need this to fill out the
--urloption in the next step.
Use the WP-CLI
core installcommand to install WordPress on the Dev environment:
terminus wp tessa-site-wp.dev -- core install --url=https://dev-tessa-site-wp.pantheonsite.io --title="Terminus Demo Site" --admin_user=admin --admin_password=changemelater --firstname.lastname@example.org
As a reminder, WP-CLI is the command line utility for WordPress itself. Terminus is simply passing through the WP-CLI commands to the site on Pantheon. To get a full list of WP-CLI commands run:
terminus wp tessa-site-wp.dev -- help
--signifies the end of the Terminus options, anything after
--gets passed straight to WP-CLI.
Create the Test environment:
terminus env:deploy tessa-site-wp.test --updatedb --note="Initialize the Test environment"
Create the Live environment:
terminus env:deploy tessa-site-wp.live --updatedb --note="Initialize the Live environment"
Instead of having to type the site name out, let's export our site name to a variable so we can copy/paste the remainder of our commands:
This sets an environment variable named
$TERMINUS_SITEwith the value
tessa-site-wp. Anytime we use the variable name it's replaced in the executed command with the value.
We can test this by echoing our variable:
You can now copy and paste the remainder of these commands without replacing the site name, as they use the
Let's see our new variable in action. Get the connection information for the Dev environment:
terminus connection:info $TERMINUS_SITE.dev
Install and activate the Contact Form 7 plugin:
terminus wp $TERMINUS_SITE.dev -- plugin install contact-form-7 --activate
If you have the Site Dashboard open, you'll see that 78 files have changed and are ready to commit in the yellow box. You can use the Site Dashboard interface to review file changes and commit, but we'll continue on the command line.
Review the file changes:
terminus env:diffstat $TERMINUS_SITE.dev
Commit your changes to the Dev environment:
terminus env:commit $TERMINUS_SITE.dev --message="Install CF7"
If you refer back to the Site Dashboard, you'll see the commit on the Dev environment:
Deploy the code to Test and pull content down from Live:
terminus env:deploy $TERMINUS_SITE.test --sync-content --updatedb --cc --note="Deploy C7 plugin"
--sync-contentoption will pull the database and files down from the Live environment. In a real-world scenario, your content editors most likely have added posts and files in the Live environment. For proper testing, you want those updates present on the Test environment with your deployed code. For more information on options for the this command, run
terminus env:deploy -h.
Activate the Contact Form 7 plugin on the Test environment by making a manual configuration change:
terminus wp $TERMINUS_SITE.test -- plugin activate contact-form-7
Once you've experimented in the Test environment and verified that your new plugin is working, and everything else is still in working order, deploy to Live:
terminus env:deploy $TERMINUS_SITE.live --updatedb --cc --note="Deploy after CF7 Install"
We don't need the
--sync-contentflag when going to the Live environment because that environment already has our canonical database.
Activate the Contact Form 7 plugin on the Live environment by making a manual configuration change:
terminus wp $TERMINUS_SITE.live -- plugin activate contact-form-7
For this example, manually applying configuration changes is a simple and short task. We're only activating one plugin on each environment. However, complex configuration changes are best managed in code so you can pull fresh content from Live while bringing in the site settings from Dev.
Now that you have WordPress installed, let's make it look a little better by adding a new theme. The WordPress theme repository has a plethora of free and paid themes you can install to customize your site. For this example we will use the Shapely theme.
Install and activate the Shapely theme:
terminus wp $TERMINUS_SITE.dev -- theme install shapely --activate
Check out the Dev environment's site URL to see the new theme in action. The
terminus env:infocommand from earlier gives us the URL. Here it is again with our environment variable:
terminus env:info $TERMINUS_SITE.dev --field=domain
Commit your changes to the Dev environment:
terminus env:commit $TERMINUS_SITE.dev --message="Install shapely theme"
terminus wp $TERMINUS_SITE.dev -- scaffold child-theme Tessa-child-theme --parent_theme=shapely
You should see the new theme within Appearance > Themes of the WordPress Dashboard:
Now you're ready to edit your child theme. This allows your parent theme, in our case Shapely, to receive updates without conflict or interference to the functionality of the site.
Apply configuration changes, such as activating the child theme, then make sure everything looks good on the Dev environment's site URL.
Commit your changes to the Dev environment:
terminus env:commit $TERMINUS_SITE.dev --message="Create Child of Shapely Theme"
Deploy the themes to Test and pull content down from Live:
terminus env:deploy $TERMINUS_SITE.test --sync-content --updatedb --cc --note="Deploy Themes"
Apply configuration changes and make sure everything looks good on the Test environment's site URL.
Deploy code to Live, then apply configuration changes:
terminus env:deploy $TERMINUS_SITE.live --updatedb --cc --note="Deploy Themes"
If you're a developer who lives in the command line, you now see the power of Terminus and WP-CLI. This guide has just scratched the surface of what can be done. Terminus provides the power to manage most aspects of your Pantheon sites, while tools like WP-CLI (and Drush for Drupal) give you the power to manage the inner workings of your WordPress powered site. Now you're ready to take the Sandbox site we've setup and explore on your own to see what else is possible.
Here are some suggestions on where to go from here: