CLI
The Uniform CLI enables you to interact with Uniform from a command-line interface.
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
- Install in a project
Installing the CLI globally allows you to run the uniform
command from any terminal prompt.
Open a terminal.
Enter the following command:
npm i @uniformdev/cli -g
Enter the following command:
uniform --version
About this stepThis confirms that theuniform
command is available.
@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 referenceInstalling the CLI in a project allows you to run the uniform
command from scripts in package.json.
Open a terminal in the root of your project.
Enter the following command:
- npm
- pnpm
- yarn
npm i @uniformdev/cli
pnpm i @uniformdev/cli
yarn add @uniformdev/cli
@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 referenceAPI 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
- CLI command switches
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 project ID | UNIFORM_PROJECT_ID |
|
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 project ID | -p --project |
|
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
- Npm script
These steps will you to download the manifest to a file manifest.json
from a terminal.
If it is not already installed, install the CLI.
If it is not already installed, install the package
@uniformdev/context
globally.Create an API key with the following permissions:
Uniform Context > Manifest > Read
Run the following command:
uniform context manifest download \
-o ./manifest.json \
-p <UNIFORM_PROJECT_ID> \
-k <UNIFORM API KEY>
manifest.json
is created.These steps will allow you to download the manifest to a file manifest.json
using an npm script.
If it is not already installed, install the CLI.
If it is not already installed, install the package
@uniformdev/context
in the project.Create an API key with the following permissions:
Uniform Context > Manifest > Read
Add the following file:
/.envUNIFORM_PROJECT_ID=<UNIFORM PROJECT ID>
UNIFORM_API_KEY=<UNIFORM API KEY>Make the following change:
{
...
"scripts": {
"download:manifest": "uniform context manifest download -o ./manifest.json",
...
}
...
}You can run the command from a terminal, or as a part of another npm script using the following command:
- npm
- pnpm
- yarn
npm run download:manifest
pnpm download:manifest
yarn download:manifest
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
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.
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.