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.

Install globally

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

Install in a project

Installing the CLI in a project allows you to run the uniform command from scripts in package.json.

1. Open a terminal in the root of your project.

2. Enter the following command:

   npm

   npm i @uniformdev/cli

   pnpm

   pnpm i @uniformdev/cli

   yarn

   yarn add @uniformdev/cli

tip

If you install the CLI in a project, you might need to install other packages in the project 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 in the project. 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:

Environment variables

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

Value	Environment variable name	Example
Uniform API key	UNIFORM_API_KEY	UNIFORM_API_KEY=<API key>
Uniform project ID	UNIFORM_PROJECT_ID	UNIFORM_PROJECT_ID=<project ID>

CLI command switches

Passing these values to the command you run gives you the ability to be very explicit about what you want to happen.

Value	Switch	Example
Uniform API key	--apiKey	uniform context signal list -k <API key>
Uniform project ID	-p --project	uniform context signal list -p <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.

Terminal

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.

Npm script

These steps will allow you to download the manifest to a file manifest.json using an npm script.

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

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

3. Create an API key with the following permissions:

   • Uniform Context > Manifest > Read

4. Add the following file:

   /.env

   UNIFORM_PROJECT_ID=<UNIFORM PROJECT ID>
   UNIFORM_API_KEY=<UNIFORM API KEY>

5. Make the following change:

   {
     ...
     "scripts": {
       "download:manifest": "uniform context manifest download -o ./manifest.json",
       ...
     }
     ...
   }

6. You can run the command from a terminal, or as a part of another npm script using the following command:

   npm

    npm run download:manifest

   pnpm

   pnpm download:manifest

   yarn

   yarn download:manifest

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.

Exporting artifacts to a single file

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

Troubleshooting

If you get the following error message, this means a package is missing:

Unknown arguments: canvas, component, pull, ./my-package.yaml

In order to pull components from your Uniform project, you must install the package @uniformdev/canvas. Whether this package must be installed globally or in a project depends on how you installed the CLI.

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

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 file my-package.yaml now contains components, 
# compositions, and signals.

Troubleshooting

If you get the following error message, this means a package is missing:

Unknown arguments: context, signal, pull, ./my-package.yaml

In order to pull components from your Uniform project, you must install the package @uniformdev/context. Whether this package must be installed globally or in a project depends on how you installed the CLI.

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