# Installation and setup

> This section describes how to install and setup the Uniform CLI so you can use it to backup and restore assets from your Uniform project.

Source: https://docs.uniform.app/docs/guides/cli/installation-and-setup

This section describes how to install and setup the Uniform
CLI so you can use it to backup and restore assets from your
Uniform project.

## Configure the Uniform CLI

The Uniform CLI is provided in an npm package. This package
can be installed in a couple of different ways, depending on your needs and where you are in your process.

- If you are creating a project you have to [invoke the CLI globally](#invoke-globally) because there are no project dependencies yet.
- If you're working with an [established project](#execute-within-a-project), you'll need to include project dependencies, like the version.

### Execute within a project

Installing the CLI in a project allows you to run the `uniform`
command from scripts in `package.json`. Uniform recommends this method for active development work because it lets projects reference independent CLI versions.

1. Open a terminal in the root of your project.
2. Enter the following command:

   `npm`

   ```shell
   npm i -D @uniformdev/cli@latest
   ```

   `pnpm`

   ```shell
   pnpm i -D @uniformdev/cli@latest
   ```

   `yarn`

   ```shell
   yarn add -D @uniformdev/cli@latest
   ```
3. To test that the command is available, enter the following command:

   ```shell
   npx uniform --version
   ```
4. The following is an example of a script that uses a `uniform` command:

   `package.json`

   ```json
   {
     "name": "my-package",
     "version": "0.1.0",
     "private": true,
     "scripts": {
       "uniform:version": "uniform --version"
     },
     "devDependencies": {
       "@uniformdev/cli": "latest"
     }
   }
   ```

### Invoke 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:

   ```shell
   npm i @uniformdev/cli@latest -g
   ```
3. To test that the command is available, enter the following command:

   ```shell
   uniform --version
   ```

## Authenticate

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's 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.

These values can be set in a couple of different ways.

### Environment variables

When these values are set as environment variables, you don't
need to explicitly pass them to each command you run.

| Value | Environment variable name | Example |
| --- | --- | --- |
| Uniform API key | `UNIFORM_CLI_API_KEY` | UNIFORM_CLI_API_KEY=<API key> |
| Uniform project ID | `UNIFORM_PROJECT_ID` | UNIFORM_PROJECT_ID=<project ID> |

> **Note:**
>
> You should use `UNIFORM_CLI_API_KEY` for access through the CLI only, to safely give that API key write permissions (if needed). For read-only access in your application, define a separate API key `UNIFORM_API_KEY` instead.

The following demonstrates how these variables can be set in an `.env` file:

_For the US region:_

`.env`

```properties
UNIFORM_CLI_API_KEY=<api-key>
UNIFORM_PROJECT_ID=<project-id>
```

_For the EU region:_

> **Info:**
>
> For EU projects, when creating an API key you can copy the complete `.env` settings that include all EU-specific endpoints:

`.env`

```properties
UNIFORM_CLI_API_KEY =<api-key>
UNIFORM_PROJECT_ID=<project-id>

# EU region endpoints
UNIFORM_CLI_BASE_EDGE_URL=https://eu.uniform.global
UNIFORM_CLI_BASE_URL=https://eu.uniform.app
```

See the [regions guide](https://docs.uniform.app/docs/guides/regions) for more information about regional configuration.

### 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 |
| --- | --- |
| Uniform API key | `--apiKey` |
| Uniform project ID | `-p, --project` |

The following demonstrates a command where the API key and project ID are specified using switches:

```shell
uniform canvas composition list --apiKey AAA... --project BBB...
```

### Verify your credentials

Use `whoami` to check which credentials the CLI resolved and what they point at:

```shell
uniform whoami
```

The command reports the project and team your configuration resolves to, the masked API key in
use, and the API hosts you have configured. Use it to confirm a `.env` file or CI environment is
wired up correctly before running a command that changes something.

> **Use an AI coding assistant:**
>
> The [`uniform-sdk`](https://github.com/uniformdev/agent-skills/tree/main/skills/uniform-sdk) agent skill teaches coding assistants such as Claude Code, Codex, Cursor, and Copilot how to authenticate with Uniform, configure the CLI, resolve routes, and read and write compositions, entries, and content types with the content API clients. To install it, see [Uniform agent skills](https://docs.uniform.app/docs/guides/ai/agent-skills).