# Profiles and multi-project setup

A **profile** is a named configuration block inside `datocms.config.json` that points the CLI at a specific DatoCMS project. When your repo only talks to one project, the `default` profile (created automatically by `datocms link`) is all you need. When your repo talks to **multiple** DatoCMS projects (for example, a blueprint project and several client projects), you create additional profiles, and select which one each command operates on.

> [!NOTE] Profiles vs environments
> Profiles are about separating **different projects** or **authentication contexts**, not different environments of the same project. To target a sandbox environment of an already-selected project, use the `--environment` flag instead.

## Creating an additional profile

Run `link` again, passing a profile name:

Terminal window

```bash
npx datocms link --profile=client_a
```

This appends a new profile block to `datocms.config.json`:

```json5
{
  "profiles": {
    "default": {
      "siteId": "12345",
      "organizationId": "67890",
      // ...
    },
    "client_a": {
      "siteId": "99999",
      "organizationId": "88888",
      // ...
    }
  }
}
```

## Selecting the active profile

When you run a command, the CLI picks the active profile in this order:

1.  `--profile=<id>` flag on the command
    
2.  `DATOCMS_PROFILE=<id>` environment variable
    
3.  `default` profile in `datocms.config.json`
    

So these two commands are equivalent:

Terminal window

```bash
npx datocms migrations:run --profile=client_a
DATOCMS_PROFILE=client_a npx datocms migrations:run
```

## Token resolution per profile

When the CLI needs an API token for the active profile, it looks for one in this order:

1.  `--api-token` flag on the command
    
2.  The linked project's OAuth credentials (for profiles created via `datocms login` + `datocms link`)
    
3.  An environment variable, named after the profile: - the `default` profile reads from `DATOCMS_API_TOKEN` - a `client_a` profile reads from `DATOCMS_CLIENT_A_PROFILE_API_TOKEN` - any other profile follows the same `DATOCMS_<PROFILE>_PROFILE_API_TOKEN` convention
    

If you want a custom environment variable name for a profile (for example because your CI provider already has a token under a different name), set the `apiTokenEnvName` property on the profile:

```json5
{
  "profiles": {
    "client_a": {
      "siteId": "99999",
      "apiTokenEnvName": "CLIENT_A_TOKEN"
    }
  }
}
```

> [!WARNING] CDA tokens don't work with the CLI
> The CLI talks to the Content Management API, so the token must have CMA access (`can_access_cma: true`). Read-only CDA tokens like `DATOCMS_READONLY_API_TOKEN` or `NEXT_PUBLIC_DATOCMS_API_TOKEN` won't work.

## Other profile-level configuration

Beyond `siteId` and `apiTokenEnvName`, every profile accepts a few additional properties:

-   `organizationId`: the DatoCMS organization the project belongs to
-   `logLevel`: `NONE`, `BASIC`, `BODY`, or `BODY_AND_HEADERS` (verbosity of CLI output)
    
-   `logMode`: `stdout`, `file`, or `directory`
-   `baseUrl`: for self-hosted or staging DatoCMS instances
    
-   `migrations.directory`: path where migration scripts live
-   `migrations.modelApiKey`: the API key of the DatoCMS model used to track applied migrations
    
-   `migrations.template`: path to a custom migration template file
-   `migrations.tsconfig`: path to a custom `tsconfig.json` for migrations
    

## Use case: keeping multiple projects in sync

A common reason to use profiles is the **blueprint → client** workflow: you maintain a "blueprint" DatoCMS project where you evolve the schema, and you propagate the same migrations to multiple client projects. See [Keeping multiple DatoCMS projects in sync](https://www.datocms.com/docs/scripting-migrations/keeping-multiple-datocms-projects-in-sync.md) for the full workflow.

## Removing a profile

To remove a profile from `datocms.config.json`:

Terminal window

```bash
npx datocms unlink --profile=client_a
```

## Related content in "DatoCMS CLI"

- [CLI Overview](https://www.datocms.com/docs/cli.md)
- [Environment, migration and maintenance commands](https://www.datocms.com/docs/cli/environment-migration-and-maintenance-commands.md)
- [Generating TypeScript types from your schema](https://www.datocms.com/docs/cli/generating-typescript-schema.md)
- [Importing content from other CMSs](https://www.datocms.com/docs/cli/importing-from-other-cms.md)
- [CLI for AI coding agents](https://www.datocms.com/docs/cli/cli-commands-for-ai-coding-agents.md)
- [Authenticate with an API token](https://www.datocms.com/docs/cli/authenticate-with-api-token.md)
- [Profiles and multi-project setup](https://www.datocms.com/docs/cli/profiles-and-multi-project-setup.md)