WP-CLI

WP-CLI is a powerful and extensible way to interact with WordPress from the command line. WP-CLI is supported on VIP as a beta feature via our VIP-CLI tool.

Most things you can do with WordPress core have an equivalent command in WP-CLI:

Getting Started

To get started, first install the latest version of VIP CLI:

npm i -g @automattic/vip

Interactive Shell

The easiest way to use WP-CLI is to use the interactive shell mode provided by VIP CLI. This feature provides a terminal-like interface into your WordPress site:

vip @my-site -- wp

my-site.production:~$ wp option get home
https://example.com
my-site.production:~$ wp cache delete my-cache-key my-cache-group
Success: Object deleted.
my-site.production:~$ 

Using the interactive shell mode is a convenient way to run multiple commands on the same environment and behaves much like a standard terminal or SSH session would.

Direct Commands

WP-CLI commands can also be run directly without the interactive shell mode, just like any normal command:

vip @my-site.production -- wp option get home
vip @my-site.staging -- wp post list --posts_per_page=100 --url=example.com/fr
vip @my-site.develop -- wp cache delete some-key

Running commands directly allows the output to be redirected and piped for creating powerful workflows and tools:

vip @my-site.develop -- wp user list --format=json | jq
vip @my-site.staging -- wp term list category --format=csv > category.csv

Note: In the examples above, the double dash (--) before wp separates arguments of the vip command from those of the wp command. You should always include them to avoid unexpected issues due to parameter conflicts.

Audit Log

For greater visibility into how WP-CLI is being used, the VIP Dashboard includes a log of all WP-CLI commands run on your applications and environments. To view the log, log in to the Dashboard and select “WP-CLI” when viewing an application.

Allowed Commands

As WP-CLI support is still in beta, only built-in commands are supported at this time. In the near future, we’ll be opening access to custom commands.

Here is the current list of supported commands:

wp cache add
wp cache decr
wp cache delete
wp cache get
wp cache incr
wp cache replace
wp cache set
wp cache type
wp cap (all)
wp cli version
wp comment approve
wp comment count
wp comment create
wp comment delete
wp comment exists
wp comment get
wp comment list
wp comment meta
wp comment recount
wp comment spam
wp comment status
wp comment trash
wp comment unapprove
wp comment unspam
wp comment untrash
wp comment update
wp core version
wp cron (all)
wp embed (all)
wp help (all)
wp language core activate
wp language core is-installed
wp language core list
wp language plugin is-installed
wp language plugin list
wp language theme is-installed
wp language theme list
wp media image-size
wp menu (all)
wp network (all)
wp option (all)
wp plugin activate
wp plugin deactivate
wp plugin get
wp plugin is-active
wp plugin is-installed
wp plugin list
wp plugin path
wp plugin search
wp plugin status
wp plugin toggle
wp plugin verify-checksums
wp post create
wp post delete
wp post exists
wp post get
wp post list
wp post meta
wp post term
wp post update
wp post-type (all)
wp rewrite (all)
wp role (all)
wp sidebar (all)
wp site activate
wp site archive
wp site create
wp site deactivate
wp site delete
wp site list
wp site mature
wp site meta
wp site option
wp site private
wp site public
wp site spam
wp site switch-language
wp site unarchive
wp site unmature
wp site unspam
wp super-admin (all)
wp taxonomy (all)
wp term create
wp term delete
wp term get
wp term list
wp term meta
wp term recount
wp term update
wp theme activate
wp theme disable
wp theme enable
wp theme get
wp theme is-active
wp theme is-installed
wp theme list
wp theme mod
wp theme path
wp theme search
wp theme status
wp transient (all)
wp user add-cap
wp user add-role
wp user check-password
wp user create
wp user delete
wp user get
wp user list
wp user list-caps
wp user meta
wp user remove-cap
wp user remove-role
wp user reset-password
wp user session
wp user set-role
wp user spam
wp user term
wp user unspam
wp user update
wp widget (all)
wp akismet check
wp akismet recheck_queue
wp akismet stats
wp jetpack get_stats
wp jetpack module
wp jetpack options
wp jetpack publicize
wp jetpack sitemap
wp jetpack status
wp jetpack test-connection

Manually logging errors in New Relic

For debugging purposes, you may want to manually log custom errors in PHP code using the trigger_error() function. However, on VIP Go, you have the ability to log custom errors in New Relic using its methods.

The function newrelic_notice_error() is available to log custom errors in New Relic. To trigger an error, you can implement something like the following:

if ( extension_loaded( 'newrelic' ) ) {
	newrelic_notice_error( 'My custom error message' );
}

The function documentation is available here.

Note: if there are multiple calls to newrelic_notice_error() in a single transaction, the PHP agent will retain the exception from the last call only.

Automated build and deploy on VIP Go

VIP Go has built-in support for CI/CD integration. Our system allows you to use a Continuous Integration service like Circle CI to run your build processes (which may include tasks like optimizing static resources, bundling CSS and JS, using composer to fetch and install dependencies, etc.) and then deploy a built copy to your environment.

How does it work?

The following example describes how a production site is developed and deployed using a build and deploy flow:

  1. Branch from master for a new feature
  2. Make the necessary modifications to your source files and committed them to the branch.
  3. Commit any changes to your dependencies, e.g. package.json, package.lock, but .gitignore the directories and files that npm modifies, e.g. /node_modules/ and anything else that gets built
  4. Create a pull request, get it reviewed and approved, then merge to master
  5. Build: Your build steps run on the CI service.
  6. Deploy: Our deploy script commits and pushes the build code to the master-built branch (and from there it is immediately deployed to your production site)

We have specific instructions below for Travis CI or Circle CI. If you wish to use your own script or your own CI service, you are welcome to do so; the instructions below and scripts referenced are provided as a convenience only.

How do I build my code?

It is up to you and your team to develop a method to build, e.g. run npm install, transpile, optimize, concatenate, minify, etc, your code. You should develop the method so that it can be automatically run by a script on a Continuous Integration (CI) service, without intervention from a human.

You should also ensure any versioning updates (needed for cache busting, etc) is part of the build process or part of the commit that triggers the build.

When running the build process for production, i.e. master-built, you should ensure that your build process does not include development dependencies. You might also want to ensure that your CI script tests the build, and flags any issues to your team.

What branches should I deploy built code to?

Your deployed branch should end in -built, e.g. if your working branch is master (for your production environment) then your built branch should be master-built, for your Develop environment your working branch should be develop and your built and deployed branch should be develop-built.

Should I commit directly to my built branches?

No. You should never push code to your build branches, e.g. master-built, you should only ever push to your working branch, e.g. master, which should then build the code and push a commit to your build branch.

My built files are in .gitignore! How do I deploy them?

By default, files and folders referenced in your repo’s .gitignore file will not be pushed to master-branch. This usually includes files generated by your build process, which is actually the opposite result we want here!

To allow the built files to be pushed to your built branch, you can create and use a .deployignore file. This file acts as a replacement for all .gitignore files in your repo. When preparing the deploy, our script removes all .gitignore files and uses .deployignore as the canonical, global .gitignore instead.

If you’d like to use a .deployignore file, you should doing the following:

  1. Make a copy your global gitignore file and name it .deployignore.
    • (If you don’t have one, feel free to use this one as a starting point.)
  2. Review any other .gitignore files in your repo and make sure any relevant rules are copied over to the .deployignore file. (You may need to update paths for these rules so that they start from the root of the repo).
  3. Remove any rules that reference built or auto-generated files that do need to be deployed.
  4. (Optional) Add any rules that reference source files that do not need to be deployed.

As an example, here’s an trimmed-down .gitignore file:

# node_modules should almost never be committed.
node_modules

# /plugins/my-ui/src is omitted here since we do want that committed for development purposes.

# This is where our built files are generated. Don't need to commit it.
/plugins/my-ui/dist

And the .deployignore file derived from that:

# node_modules should almost never be committed.
node_modules

# Our source files don't need to be deployed.
/plugins/my-ui/src

# /plugins/my-ui/dist is omitted here since we do want it deployed.

Configuring builds on Circle CI

It’s a good idea to read the Circle CI getting started documentation (but don’t add the suggested Circle CI config at this point).

The following instructions reference the master and master-built branch, but can be adapted for other branches, e.g. develop and develop-built.

Before you start: We’ll need to enable Circle CI for your repository. Open a ticket and we’ll take care of that for you. Once done, you can follow the remaining steps below.

  1. Generate a deploy key. This key can be generated locally, as it will be used only by Circle CI to communicate with your GitHub repository; it does not come from or communicate with our servers.
  2. On GitHub, add the key to your repository under “Settings > Deploy Keys”. Note that the key needs “write” access.
  3. On Circle CI, you’ll need to:
    1. navigate to https://circleci.com/gh/wpcomvip/your-github-repo (use your GitHub account to access).
    2. add the key to your project (Settings | SSH Permissions). Note: It’s important that you set the hostname to github.com.
  4. Create a new Pull Request to add or adapt a config for Circle CI:
    • If you have no Circle CI config in your repository, copy this config to .circleci/config.yml in your repo; you will need to add the build command(s) you’re using in the section under “@TODO: Configure build steps”
    • If you already have a Circle CI config, you’ll need to:
      1. Add the build command(s), referencing the section in our example config commented with “@TODO: Configure build steps”
      2. Add the two sets of two lines referenced by the “REQUIRED:” comments
    • Important: Add the deploy key’s fingerprint to the repo’s /.circleci/config.yml file in the master branch.
  5. If necessary, add and update a .deployignore file.
  6. You can now trigger a build by merging a PR to master (this can be a non-significant change like a code comment). If the setup worked, Circle CI will have pushed a built copy of your application to the master-built branch on GitHub. You should verify the branch exists and contains the changes you made.
  7. Now contact VIP again to have your environment updated to deploy from master-built
  8. And that’s it! Happy building!

Testing your CircleCI Config

If your build script is failing on CircleCI, it might be a good idea to test your config locally since new builds will only run when a commit is made.  CircleCI has a Local CLI you can use with Docker to execute jobs.  Take a look at the Using the CircleCI Local CLI documentation.  You can validate your config.yml file using the Local CLI, but it only checks for syntax errors and not build errors.

Installing CircleCI Config on macOS or Linux:

  • Public CLI Github Repository: https://github.com/CircleCI-Public/circleci-cli
  • Install using Homebrew, cURL, or Snapcraft
  • Make sure you have Docker installed and you’re logged in with docker login (Tip: Many people report logging in with your email might cause issues so if you encounter that problem, try logging in with your Docker username)
  • Connect with your CircleCI account: circleci setup
  • Now you can validate a config file circleci config validate or run a job locally with circleci local execute --job JOBNAME (Note: this command only runs a single job and not a workflow)

Configuring builds on Travis CI

It’s a good idea to read the Travis CI getting started documentation, but don’t add the Travis CI config at this point.

  1. Visit https://travis-ci.com, authenticate with your GitHub account, and add your repository to Travis CI
  2. Create or adapt a config for Travis CI:
    • If you have no Travis CI config in your repository, copy this config to .travis.yml in your repo; you will need to add the build command(s) you’re using in the section under “@TODO: Configure build steps”
    • If you already have a config, you’ll need to:
      1. Add the build command(s), referencing the before_script section in our example config commented with “@TODO: Configure build steps”
      2. Add the two sets of two lines referenced by the “REQUIRED:” comments
  3. Ensure you have a machine user, this is a regular GitHub user account which is used purely for scripted functions, e.g. used by Travis CI to commit and push the built code (GitHub call this user a “machine user”):
    • If you have no dedicated “machine user” account, create a new GitHub account, named appropriately.
    • If you already have a machine user for your team, then use that account for the following steps.
  4. Setup a key pair for your machine user:
    1. Use the commandline on your local machine to create a public private key pair (documentation)
    2. Set the public portion of the key pair as a deploy key with write permissions on the GitHub repository (documentation)
    3. Add the private key as a setting on your Travis repository (see “Adding a deploy key in repository settings on Travis CI” below)
  5. If necessary, add and update a .deployignore file.
  6. Merge a PR to your master branch… it should be built by Travis CI, committed to your master-built branch, and pushed up to GitHub (verify the branch now exists on GitHub and contains the changes you made)
  7. Contact VIP to have your environment changed to deploy from master-built
  8. …that’s it!

Adding a deploy key as a repository variable on Travis CI

Please read these instructions through before executing the steps.

Add the public portion of the key as a deploy key on your GitHub repository; GitHub documentation on deploy keys.

Set the private portion of the key as a repository variable in the Travis settings. You will need to replace newlines with \n and surround it with double quotes, e.g. “THIS\nIS\A\KEY\nABC\n123\n”; Travis documentation on repository variables in settings.

You must set the “Display value in build log” toggle for the repository variable to “off”.

You must name the Travis setting that contains the key BUILT_BRANCH_DEPLOY_KEY.

Other Notes

How is code reviewed when using automated build and deploy?

If you are on a plan where we review your code, we will review the source code that your team writes and commits to your development branch.

However, third-party dependencies brought in by the build process will not be reviewed (e.g. Javascript dependencies added via npm or yarn or PHP SDKs/plugins/libraries added via Composer).

Where is the source code for the deploy script?

You can see the source code on the Automattic/vip-go-build Github repo.

My CI service is down or broken, how do I deploy files?

The step that you use to build files in your CI service should be scripted, by the nature of CI tasks. You should be able to follow this process:

  1. Clone your repo.
  2. Checkout the working branch with the code you need to build (e.g. master).
  3. Run your build process (e.g. npm install).
  4. Create another clone of your repo, and checkout the deployment/built branch (e.g. git checkout master-built).
  5. Copy changes from the development copy to the deployment copy using a tool like rsync.
  6. Verify your changes: they should only include built code (and not development modules and dependencies).
  7. Commit and push the changes the remote repository (e.g. git push origin master-built).
    • Note: you do not need to open a PR, unless you would like a quick validation review from the VIP team.
  8. At this point, our infrastructure detects the changes and deploys them to your application.

VIP CLI

VIP CLI is the command line interface for VIP Go. You can use VIP CLI to interact with your VIP applications, query information about your applications, and perform actions like syncing data from production to development environments.

VIP CLI is aimed at developers, so familiarity with installing CLI applications and using the Terminal is required. VIP also offers the web-based VIP Dashboard, which will provide access to similar functionality in a graphical user interface.

What commands does the CLI offer?

You can view the available commands with the vip --help command:

$ vip --help

Usage: vip [options] [command]

Commands:

app List and modify your VIP Go apps
help Display help
logout Logout from your current session
sync Sync production to a development environment

Options:

-h, --help Output usage information
-v, --version Output the version number

Installing VIP CLI locally

VIP CLI is a Node.js Package and can be installed through a package manager like npm.

VIP CLI requires Node.js v8.9.0+ and npm v5.7.1+. If either or both are below the required versions, see the upgrade steps in our troubleshooting section below.

To begin installation, visit our VIP CLI page installation page and follow the instructions.

Note: It is extremely important not to install VIP CLI using the sudo command; if this has been done you can follow the directions below.

Specifying App and Environment

On VIP, each application has one or more environments, such as production, staging, or develop. For VIP CLI commands that run on a specific environment, VIP CLI will prompt you to choose an environment.

Environments can also be specified with an alias in the command, in the form of @<app-name>.<env>. Here’s an example command using an environment alias:

vip @wpvip.production -- wp option get home

Each environment can be specified by the unique app name, a dot separator, and the environment name. An environment’s alias can be found in the VIP Dashboard.

Troubleshooting

Status code 401

You may receive an error including the line Received status code 401, for example:

Failed to fetch apps: Error: Network error: Response not successful: Received status code 401

Please try the following:

  1. Run vip logout
  2. Run vip and follow the prompts to log in again

I can’t see all my applications

For you to access an application via VIP CLI, you must have access to the GitHubrepository for that application. If you do not see all the applications you expect when running vip app list, please follow this procedure:

  1. Check you have access to the GitHub repository for the application(s) you expect to see, if you do not have access to these repositories on GitHub then you should contact someone in your team who has admin rights or alternatively contact VIP support
  2. If you do have access to the application repository on GitHub, but you do not see the application listed via vip app list then…
  3. Run vip logout
  4. Run vip and follow the prompts to log in
  5. Run vip app list, If you are still not seeing all the applications you expect then please get in touch with VIP support

Installing Node

Please follow the Node.js project’s installation instructions.

Installing npm

Installing Node.js (instructions above) will include npm in the installation.

Upgrading Node.js

Follow the Node.js installation instructions to acquire and install the latest version of Node.js, or use the upgrade command if you installed via a package manager like Homebrew for macOS.

Upgrading npm

If you have npm installed already, you can run the following command to update to the latest version:

npm install -g npm

Fixing NPM/Node permissions

Read this npm guide: How to Prevent Permissions Errors.

If you have installed various commands with sudo you will need to reverse the process, fix the permissions errors, then install the command without the use of sudo.

Help, I used sudo to install VIP CLI!

You should not use sudo to fix access permissions; instead, please see “Fixing permissions” above.

WARN install EACCES: permission denied

See “Fixing permissions” above.

VIP Dashboard

The VIP Dashboard is the home for managing your VIP Go applications. Upon signing in, a list of all your apps is visible:

For updates & news on VIP, click on the info icon in the upper right-hand corner. You will also find shortcuts to documentation.

Click on your profile icon to set up the VIP CLI.

Tools

Currently, each application has Dashboard, Sync, and Domains tools:


Dashboard
– Displays an activity log for each of the app’s environments.
Click on the shortcuts for each environment to see the corresponding WordPress login and GitHub repositories.

Sync – Features a real-time data syncing tool to copy content from production to a child environment. Find out more about data sync here.

Domains – View a list of your domains available to the app. Switch environments and see which domains are associated with each environment, map domains, view DNS Instructions, and provision LE Certificates.

As we continue to design and develop new platform functionality, we are looking for testers to provide feedback on early ideas and prototypes. If you would like to get involved, please get in touch via Zendesk.

Authentication

GitHub is used to authenticate, which allows access to VIP Go applications to be provided by checking which VIP Go repositories the user has access to.

To work with VIP Go applications on the command line, install VIP CLI.

Troubleshooting

e002 User Not Found!

This error states we were unable to find any VIP Go repositories the user has access to. If the GitHub user account does not have access to any VIP Go repositories, authentication will not be successful. 

To gain access to a VIP Go repository, please contact our Support team.

New Relic on VIP Go

New Relic is available for clients running on our VIP Go platform. New Relic is an application monitoring platform and on VIP Go, you can use it to monitor the PHP (WordPress) code and browser performance of your site or application.

If your team would like to use New Relic, please contact us and we’ll be happy to arrange access for you. We do not charge for access to New Relic.

What New Relic plan will I be running?

The New Relic plan we run is as follows

  • Web Pro Annual – this is the PHP application monitoring which covers your WordPress application code
  • Mobile Lite
  • Insights Free
  • Browser Lite
  • Synthetics Lite

The differentiation mainly affects the retention of monitoring data, with Pro elements of the plan retaining data for longer than Lite elements.

How many users can I have accessing New Relic?

As many as you require, please contact us with the email addresses of any team members who need access to your New Relic monitoring.

It is your responsibility to request leaving members of your teams have their New Relic access removed.

Can I turn off New Relic Browser Monitoring?

Yes! New Relic have some documentation on disabling Browser monitoring and real user monitoring.

Can I use the New Relic PHP API and SDK to enhance the data captured by New Relic?

New Relic maintains a suite of PHP functions which can be used to  add data to transactions, name transactions, etc, you can read more in their documentation. WordPress.com VIP uses this API to enhance the data provided by all VIP Go WordPress applications (see the code).

We don’t offer custom PHP INI configuration for individual WordPress applications (sites), but you may find that some of the configuration can be set in PHP at runtime using ini_set().

Can I use my own New Relic account?

The VIP team uses New Relic to monitor all the sites and applications on the VIP Go platform; therefore we require that your application uses the WordPress.com VIP New Relic account in order for us to continue doing so.

How do I use New Relic

New Relic themselves maintain documentation:

If you have any further questions, please feel free to contact us and we’ll be happy to help where we can.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.