Deploy Your App Via the Atlas CLI

Before you being, install the Atlas CLI and ensure that you have created your first app.

To deploy your app, log in to your WP Engine account and connect your GitHub account.

First, log in to your WP Engine account:

$ wpe auth login

After you've successfully logged in, connect your GitHub account:

$ wpe auth login github

Note: When connecting your GitHub account, you need to access the repository you created and pushed to earlier.

To work with headless apps, we need to set account context, which associates your application with WP Engine. Find your account name in the WP Engine User Portal at the top left of the navigation bar.

To set the account context, run:

$ wpe context set account YOUR_ACCOUNT_NAME

Now you should be able to run all app commands without error. To make sure, run the list command. The list will be empty until you create an app later in the guide.

$ wpe apps list

At the root of your project, create a file named wpe.json. You can replace wpe with any name you want as long as you use the .json extension. Use this file to configure your deployment.

An app only requires a few fields and does not represent a deployment. You can think of an app the same way you think of a WP Engine Portal site. App environments represent the deployment that is connected to a branch in your repo.

Copy this basic configuration into your wpe.json file:

"name": "My-First-Headless-App",
"repo": "YOUR-github-org-or-user/your-repo",
"region": "US-C",
"environments": [
"name": "Production",
"branch": "main",
"wp_environment_name": "YOUR WordPress environment name",
"env_variables": [
"value": "https://yoururl"

Replace repo with the GitHub repo you want to connect to your app. Your repo consists of the GitHub organization or user and the repo name.

For example, the GitHub repo is represented by matt-landers/headless-summit2020. Notice that it is just the repo URL without

Set the region to one of the following:

  • EU-W - Europe West
  • UK - United Kingdom
  • US-C - US Central
  • AUS-SE - Australia Southeast

Replace the value of wp_environment_name with the environment name from User Portal. For instance, if the domain name is, use env_name as wp_environment_name.

branch under the Production environment specifies the branch to watch and build.

domains can be added to your production environment, but for the purposes of this guide, we won't add a custom domain. For instructions on how to add a custom domain in a production environment, see Introduction > WP Headless Concepts > Apps and Environments.

env_variables are optional OS-level environment variables that are available to you during build and runtime. You can use these to store API secrets, your WordPress URL, etc. Access these secrets in Node via process.env.KEY.

Important: Remember that wpe.json exists in your .gitignore file. Therefore, the file does not appear in staging when committing to GitHub. You will use this config to store secrets (e.g., API keys, credentials) that you don't want to publish to GitHub.

Now that you have a valid configuration file for your app, deploy the app to the Atlas with the following command:

$ wpe apps create -f wpe.json

Next, use the get command to check the status of your deployment:

$ wpe apps get My-First-Headless-App

The get command will return the details of your app. Your app will take a few minutes to deploy. Once the deployment is complete, the get command will return the URL of your application. Copy the URL into a browser window, and you'll see your app up and running on the platform. 🎉

Now let's check out our configured developer workflow.