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 Canvas 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 Canvas 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 Canvas, this is done using serialization of the component or compositions to files on disk. These files can then be committed to source control and shared between environments.

These files are updated using the pull command (uniform canvas component pull --help) and the files are synchronized back into the configured environment using the push command (uniform canvas component push --help).

tip

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.

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.

caution

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.

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 Canvas 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

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

Limitations

At this time only components and compositions may be serialized with the CLI. We plan to add support for additional entity types in the future, such as intents and signals.