The Yext Command-Line Interface (CLI) allows a user to interact with Yext from the terminal.

The Yext CLI can be used to pull, diff, and apply your account’s configuration. For example, you can set up Yext Answers without leaving your terminal. We will continue to support the newest Yext products in the Yext CLI.

This post introduces you to the Yext CLI, with a particular focus on how to use Service Users for automation.

Problem

Our CTO wanted the Yext CLI to apply his configuration as a step in a CI (Continuous Integration) build pipeline. Our CIO required all data changes to be attributed to a specific human. How do we solve these two seemingly conflicting constraints at the same time?

Indirection solves many problems in computer science. Let’s see how we can leverage that. But first, how is this issue solved in the real, brick and mortar world?

Analogy

I have a rental property. A property manager manages the property. I have given the property manager a key to the property to keep. To service the house, he takes out the key and gives it to a plumber with the understanding that the key is only for a finite amount of time. The plumber uses the key to service the house and returns the key to the property manager. As the property owner, I do not need to be involved in any of this. However, I am still attributed to any changes to the house. For example, if there is a housing code violation in the house, I will still be on the hook for that by the Government and not the plumber or the property manager.

Let’s take this analogy to our service user concept.

Service User

We create a Service User or machine user under an account that generates a key. Then we save the generated key into Vault, the manager of the keys. Vault provides the key to a script that activates the service user using the key. The Auth Server allows an hour for the Service User to make changes to an account. For a longer duration, the Service User needs to be re-activated using the key. Service User performs actions on an account. The key stays in the Vault and does not leak to the outside world. The attributions of these actions include the creator of the Service User in addition to the Service User.

A Service User can be created only under a session by the account owner. A Service User can make changes to an account. In the case of multiple owners of the house, the owner who made the service user will be attributed. This situation is slightly different from real-life where all the owners will be on the hook.

A service user is valid forever unless specifically deleted. The session that the script gets into is valid only for an hour and needs a re-activation for the next hour. The Yext CLI sends the key to the auth server on activate. The auth server decrypts the key and matches it against known service users. If matched, the auth server returns an access code valid for that account for an hour.

While Service User is the applier to script a change to an account, the solution configuration modifications in the repositories or locally can be scripted by our tool called Solution Updater or Sud.

Sud (Solution Updater) is a tool to automate modification of your account or solution configurations present in a repository or locally. You can use Sud to bulk modify multiple configuration repositories with a single command. Once you have collected some Cac (configuration as code) resources as JSON files, you may want to maintain them using scripts. We maintain Yext Solution Templates using Sud at Yext.

We have developed the sud tool and have open-sourced it to help the users maintain their solution repositories.

Sud uses our forked JSON patch library that implements ordering to update JSON files in-place.

Sud, along with the Yext CLI, unlocks the power of the CLI for you.

The Power of the CLI

In this section, we will install and use the Yext CLI to write an example script. The script will enable hotel entity type whenever it is run.

Setup

To set up for scripting for an account once, we will install the Yext CLI and create a Service User while in a session. We will also install Sud.

1. Install the Yext CLI and link to an account as in the CLI documentation.

   brew install yext/tap/yext and yext init

2. Run service-users command group to create a service user with the chosen name and path to where you want to generate the key file.

   For example, yext service-users create runner-service-user ./runner.key

3. Install sud our solution updater tool to bulk edit configuration as code.

   brew install yext/tap/sud

After the one-time setup, we can work on the script to use the CLI tools.

Script

In this section, we will create a script and run it to make a change to your account. Please create a script by following the below gif, name it enable-hotel.sh

1. Activate the service user. Activating a service user changes the current credential to be the service user.

   yext service-users activate --key-file ./runner.key

   Once activated, you may pull or apply resources, as usual, using the Service User’s identity. Please note that for attribution purposes, the user who creates the service user will be part of the actor attribution for changes made using a service user.

2. Pull resources yext resources pull ~/r/my-resources
3. Enable hotel sud replace default/km/*/hotel.json --path /enabled --value true ~/r/my-resources
4. Apply the modified resource yext resources apply ~/r/my-resources/default/km/entity-type-extension/hotel.json -f

Make the script executable chmod +x enable-hotel.sh and run it.

Thus, we can make changes to an account with no human intervention but with human attribution.

Solved!

That solves the ask of our CTO to use the Yext CLI to apply without human intervention. Our CIO wanted human attribution. The creator of the service user continues to be attributed along with the service user.