Skip to main content

Context CLI

Purpose​

The Context CLI is a command line interface for the Context API. It enables you to easily automate common operational tasks with Uniform Context, for example migrating signal definitions between projects, performing bulk updates to enrichment data, and more.

Installation​

To install the Context CLI, install the following npm packages:

yarn add @uniformdev/cli @uniformdev/context

The Context CLI is a modular component of the Uniform CLI. If the Context package is installed the Context-specific commands will be available in the CLI.

Authenticating with the Uniform CLI​

The Uniform CLI uses API keys to communicate with Uniform. These give granular permissions to the API so you can lock down what the CLI is allowed to do for example in CI/CD scenarios. API keys are created in Team Settings -> API Keys. To use an API key, you must also specify the project ID that you want to use; the API key must also grant permissions to the project. The API key interface makes it easy to copy the key and project when it is created.

To use an API key with the Uniform CLI you have two options:

  • Use explicit parameters, --apiKey and --projectId, with each command to specify the key and project.
  • Use environment variables, UNIFORM_API_KEY and UNIFORM_PROJECT_ID, to set default values for the parameters.

We recommend using environment variables in most cases. The CLI supports dotenv, so you can specify them locally in a .env file if you wish.

Pulling and Pushing Between Environments​

A common operational need is to keep multiple deployment environments in sync with each other, which in the case of Uniform means multiple Projects such as "Alice's Dev", "Bob's Dev", or "Production". For Uniform, this is done using serialization of project assets, such as Uniform Context signals and enrichments, to files on disk. These files can then be committed to source control and shared between environments, or used to scaffold templates and demos.

These files are updated using the pull command (e.g. uniform context signal pull --help) and the files are synchronized back into the configured environment using the push command (e.g. uniform context signal push --help). There are several options available to control the file format, output type, and allowable actions that you can discover by issuing the help command in the CLI.

Very similar commands exist for pushing and pulling:

  • Context Signals
  • Context Enrichments
  • Context Quirks
  • Context Intents & Audiences

Another useful technique with pushing and pulling is to perform bulk updates. Since the serialized files are plain YAML (or JSON), you can use your favorite tools such as jq to modify them before pushing them back into Uniform.

Packaging​

For CI/CD environments it is generally ideal to produce a single artifact instead of many serialized files to define the state of Uniform. To support this, the Uniform CLI allows you to use the pull and push commands directly to a package file instead of multiple files on disk.

To create a package simply specify an output filename instead of an output directory:

uniform context signal pull ./my-package.yaml

Packages support holding multiple types of entities (i.e. enrichments and signal). If you pull to an existing package file, the entity type that you pull will add or overwrite any existing entities of that type in the package, for example:

uniform context enrichment pull ./my-package.yaml
uniform context signal pull ./my-package.yaml

# the my-package.yaml file now contains enrichments and signals

Publishing the changes​

For your changes to become available in a published manifest, they first need to be published. You can use the following command to publish your manifest:

uniform context manifest publish
tip

Your API key will need to have the following permissions in order to be able to publish the manifest:

  • Uniform Context - Read Drafts
  • Uniform Context - Manifest - Publish

Tips​

tip

The Context CLI is primarily intended for ad-hoc synchronization of production project data into development projects, and to scaffold starting project data. In most cases, you want the Context entities to be defined by marketers only and never overwritten by developers or CI/CD pipelines.

caution

If you are pushing many types of Context data into an empty project, the order of commands to push matter. For example an aggregate can depend on a signal input existing before they can be created.

  • Quirks
  • Signals
  • Enrichments
  • Aggregates (Intents, Audiences)