Using the WPCS CLI allows you to locally develop your Product with complete access to all the folders in your WordPress installation and send that over to WPCS. Some of the benefits of local development include: utilizing FTP, accessing the WP-config, and building custom (must-use) plugins.
Once you’re ready to push your local installation to WPCS, you can use the WPCS CLI to do so. Pushing a local installation (or more) to WPCS is just one of the features. The CLI also allows for creating snapshots, tenants, and new versions, downloading snapshots to use locally, and setting up a CI/CD pipeline.
If you have the CLI setup and you’re using it, just type “npx @wpcs.io/cli help” at any stage to browse through the different options and actions.
Setting up the CLI requires a few preparations that only take a few minutes to do. But once you’re set-up, you’ll find that the WPCS CLI is extremely easy to use and very helpful. In this recipe, we’ll use LocalWP to install and build our local WP installation.
1. Install the necessary software #
First, we must install some additional software. Takes only a few minutes to install and is for free.
2. Configure LocalWP #
Pushing a local WP installation to WPCS gives you 2 options. Push it as a:
- New Version (the development environment that hosts and influences your sites)
- New Tenant (your websites)
To use the WPCS CLI with an application such as LocalWP, your WordPress installation can be one of a few things.
For a Version, either: #
- A WordPress installation that you’ve built in LocalWP that contains all the plugins and themes that you want to use for all of your websites (they don’t have to be activated)
- An import in LocalWP of an existing website that you want to be pushed to WPCS to use as the base for your templates (Snapshots) and subsequent websites (Tenants). Here’s an article on how to import a site in LocalWP.
For Tenants: #
- Any WordPress installation that you have that has the exact same plugins and themes as whatever you’re using as your Version (you need to keep functional parity with your version if you’re uploading different installations as tenants).
Sidenote: even though your tenants need to have the same plugins, themes, and language files as your version, your Version does not need to have the same files as your tenant. It can have more. This idea lends itself to having varying tenants within the same Version.
3. Configure a .env file in your local WP-install with WPCS API keys #
To make sure that WPCS knows which Product you want to send your local installations to, you need to connect it with LocalWP using API credentials from your Product.
Open the WP folder of your local install in LocalWP and, using a visual editor such as Visual Code, make a file in the WP folder in “Public”, where also wp_config is and name it: .wpcs-cli.env
Then, add:
WPCS_DEFAULT_REGION=eu1-or-us1
WPCS_DEFAULT_API_KEY=your-api-key
WPCS_DEFAULT_API_SECRET=your-api-secret
After you’ve pasted the above, go to the WPCS Console, open up your Product and go to API keys. Click on the + button, give your API key a name and generate the key and secret.
You’re now setting up the API credentials in the .wpcs-cli.env by editing these lines:
- Choose your region: eu1 or us1 (strike what you won’t use)
- Replace the “your-api-key” line with the API key you’ve generated
- Replace the “your-api-secret” line with the API secret
Now, save the visual editor and open the site shell of the wp install from the LocalWP dashboard.
Important note: make sure the WP install is active (that means "start" the site in LocalWP).
Opening up the site shell from LocalWP brings you into the terminal.
Inside the terminal, check if the CLI works:
- Check Node: node -v
- Check WP CLI: wp —version
- npx @wpcs.io/cli check
4. Deploy local WP install to WPCS #
Now that you’re ready, use any of these commands to either create a Version or a Tenant.
Creating a Version from local: #
- npx @wpcs.io/cli local deploy --name [NAME]
Creating a Tenant from local: #
To send a local installation to WPCS as a tenant we first need to turn it into a Snapshot that WPCS can receive:
- npx @wpcs.io/cli local package
This will give you a path, that might look something like this:
- /var/folders/w_/ht692v116vn8ckq7cv2phng40000gn/T/wpcs/jobs/export_241b0e48-71e7-4f3d-abef-e46e4b13963b.tgz
Next, you enter the command that will send this Snapshot to WPCS:
- npx @wpcs.io/cli tenant create [NAME] --customSnapshotPath= [INSERT PATH]
The result would look something like this:
rogerrosweide@Rogers-MBP public % npx @wpcs.io/cli local package
/var/folders/w_/ht692v116vn8ckq7cv2phng40000gn/T/wpcs/jobs/export_ae081c11-29a5-45b2-8066-97d1bb23d6ae.tgz
rogerrosweide@Rogers-MBP public % npx @wpcs.io/cli tenant create roger --customSnapshotPath=/var/folders/w_/ht692v116vn8ckq7cv2phng40000gn/T/wpcs/jobs/export_ae081c11-29a5-45b2-8066-97d1bb23d6ae.tgz
{
id: 'd7ad9c4b-5775-43ed-8d78-c9dc6259490b',
externalId: 'd7ad9c4b-5775-43ed-8d78-c9dc6259490b',
baseDomain: 'roger-d7ad9c4b577543ed8d78c9dc6259490b.tenants.eu1.wpcs.io',
uploadUrl: 'https://s3.eu-west-1.amazonaws.com/wpcs.eu1.custom-uploads/a2f3db9b-daf1-4030-970e-c4cd23127f0f/8e275543-2480-4747-9877-f6b170b97b92/101bcd41-ef8c-4c70-ba29-47efd07dad4a.tgz?X-Amz-Expires=3600&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEBMaCWV1LXdlc3QtMSJHMEUCIHSNLpRAGYwdO3QlXDDYBl1duYD9C8aDs%2FDsLPPiQUNQAiEAsb2%2FTWjHNsvkR%2BWo%2F0K4cnWCdhwSKCsSQae2QfRxzpAqnQIILBADGgw1ODc4NjQ4Mjk2NjUiDOr8SQiNg3VQXErDLyr6AcoM%2B1DepYRBA38rWNLVkhB81qA6QnMUKOOnkWUHDojM%2Fv8CnGL3daK6HKAhLkaFQ5XgAibEQzmD5YeHze8FovqQ1abhyhbZ%2BeTwSDwRhTmMmW32uV0Tx7%2FsI90BxTPRg%2FWhBNP2LSnOl6mE3FmPHoHXAo3zg6yCbvjqzaNUUV8j8IrP0vDlpqh4xEVX2vHQedeU8Y6yoZzw7maMB2etyvdwwjdU8Ev%2FGT8gnDJqhbKT7A%2FV69uwwQdLckZBjQVY3v72lqUgMhBHeWd0QEA2Z%2BZcUUhlS6fEh%2BTRC3n1ZuZGCO5v1l3Hk7y2rUl0B6olP5tJ34VlsjMoXBgw2qXBlQY6mgGpulk%2FkmzputAjTcnRjpS9WE5rqTcMV0Vof9655wq%2BWweAnKjLt4s1H9gecptVgXx4aWcJ%2BVZouajlFalWORtY2UAzaobVvcvyWGVUrpvNzTmHdt0EUZ%2BtLMPFEHdL1sknsIPPzT6p%2Bs4on%2BVZI8%2BoBE%2FLf96HrMtbH5P2HOdcrO13j7G0tvE1Jwc1DaaPBq%2FZgMYCZ8WVPHRp&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAYRX3ZN3QZBEPSZNG/20220620/eu-west-1/s3/aws4_request&X-Amz-Date=20220620T110529Z&X-Amz-SignedHeaders=host&X-Amz-Signature=cb1a95acf9d628da6d0c691f44f6d17946a09ee45b29300cc854d45da9723f6b'
}
rogerrosweide@Rogers-MBP public %Additional commands: #
- npx @wpcs.io/cli tenant create [NAME] (if you want to create a tenant based on your current Production Version)
- npx @wpcs.io/cli tenant list (if you have several Products, to check if you’re in the right product)
☝? If at any stage you need help while using the WPCS CLI, just type “npx @wpcs.io/cli help” and explore from there. Have fun