Skip to main content

Canvas CLI

What is the Canvas CLI good for?

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

Installing the Canvas CLI

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

yarn add @uniformdev/cli @uniformdev/canvas

The Canvas CLI is a modular component of the Uniform CLI. If the Canvas package is installed the Canvas-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 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.


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

Canvas CLI Tips


In most cases component definitions should be synchronized between environments, and compositions only moved on demand to avoid overwriting author changes. The CLI also provides list, get, update and remove commands to make it easy to also work with individual entities outside the confines of a synchronization.


If you plan to push both component and composition data, ensure components push first to ensure the correct schema for the composition data is present.