Skip to main content

CLI

The Uniform CLI enables you to interact with Uniform from a command-line interface.

tip

For a detailed list of the commands that are available, see the CLI reference.

Install the CLI

The Uniform CLI is provided in an npm package. This package can be installed in a couple of different ways.

Installing the CLI globally allows you to run the uniform command from any terminal prompt.

  1. Open a terminal.

  2. Enter the following command:

    npm i @uniformdev/cli -g

  3. Enter the following command:

    uniform --version
    About this step
    This confirms that the `uniform` command is available.

tip
If you install the CLI globally, you might need to install other packages globally as well. For example, CLI commands related to classification require the @uniformdev/context package. In order for the context commands to be available, the context package must be installed globally. For more details, see the CLI reference

API keys & project IDs

The Uniform CLI uses an API key to communicate with Uniform. The API key must be specified for all commands you send using the CLI. This allows you to configure specific permissions for the API key so you can lock down what the CLI is allowed to do. For example, if you are using the CLI in a CI/CD scenario, it is probably sufficient to set read-only permissions on the API key.

When you send a command using the Uniform CLI, the command is intended for a specific Uniform project. As a result, you must also specify the Uniform project ID for all commands you send using the CLI.

There are two ways to specify these required values:

When these values are set as environment variables, you do not need to explicitly pass them to each command you run.

ValueEnvironment variable nameExample
Uniform API keyUNIFORM_API_KEY
UNIFORM_API_KEY=<API key>
Uniform project IDUNIFORM_PROJECT_ID
UNIFORM_PROJECT_ID=<project ID>
tip

For more information on the Uniform CLI tool, see the Uniform CLI reference.

Download the manifest

The Uniform manifest is a JSON file that describes the classification rules that are configured in Uniform. In order for the Uniform tracker to classify a visitor, it needs to know this configuration. As a result, the Uniform tracker needs the manifest.

These steps will you to download the manifest to a file manifest.json from a terminal.

  1. If it is not already installed, install the CLI.

  2. If it is not already installed, install the package @uniformdev/context globally.

  3. Create an API key with the following permissions:

    • Uniform Context > Manifest > Read

  4. Run the following command:

    uniform context manifest download \
    -o ./manifest.json \
    -p <UNIFORM_PROJECT_ID> \
    -k <UNIFORM API KEY>

What has changed
When the command finishes, a file manifest.json is created.

Backup & restore

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 Canvas components or compositions and 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 canvas component pull --help) and the files are synchronized back into the configured environment using the push command (e.g. uniform canvas component 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:

  • Canvas Components
  • Canvas Compositions and Patterns
  • 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 canvas component pull ./my-package.yaml

Packages support holding multiple types of entities (i.e. components and compositions). 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 canvas component pull ./my-package.yaml
uniform canvas composition pull ./my-package.yaml
uniform context signal pull ./my-package.yaml

# the my-package.yaml file now contains components, compositions, and signals