# CLI Overview

Most programmatic work with DatoCMS happens through the [Content Management API](https://www.datocms.com/docs/content-management-api.md), either via direct HTTP requests or the [JavaScript CMA client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md). On top of that API, the **DatoCMS CLI** (`datocms`) packages the recurring project workflows into ready-made terminal commands. You install it as a dev dependency in your repo, link it to a project once, and from there you can manage environments, run schema migrations, generate TypeScript types, toggle maintenance mode, import from other CMSs, and call the Content Management API directly, all without leaving the terminal.

## What you can do

Once installed and linked to a project, the CLI lets you:

-   **Set up a repo that talks to DatoCMS**: install, OAuth login, and link the project to a `datocms.config.json` file.
-   **Run schema migrations**: scaffold and execute versioned migration scripts that evolve your project's content model in a controlled way.
    
-   **Manage environments**: fork sandbox environments, promote them to primary, rename, or destroy them.
-   **Generate TypeScript types**: produce a typed schema of your project for use in your application code and migrations.
    
-   **Toggle maintenance mode**: lock the project during deploys or other sensitive operations.
-   **Import content from other CMSs**: official plugins for Contentful and WordPress.
    
-   **Manage multiple projects**: use profiles to keep blueprint and client projects in sync from the same repo.
    

## How the CLI relates to MCP Server and Agent Skills

Two other tools build on top of the CLI or complement it:

-   [Agent Skills](https://www.datocms.com/docs/agent-skills.md) are a knowledge package built on top of this CLI. Install them in your editor and an AI coding agent (Claude Code, Codex, Cursor, …) gains the ability to do everything this section describes, plus content modelling guidance, frontend integration patterns, and plugin authoring expertise. The Skills handle CLI bootstrap for you, guiding you through install, `login`, and `link` when needed.
-   [MCP Server](https://www.datocms.com/docs/mcp-server.md) is the right choice when there is no local terminal to work in (for example, an editor or product manager interacting with DatoCMS from a web-based AI assistant).
    

If you are a developer working in a terminal, the CLI is the starting point. Install Agent Skills on top of it to unlock agentic workflows.

## Install the CLI

Install the `datocms` package as a dev dependency of your repo:

Terminal window

```bash
npm install --save-dev datocms
```

## Authenticate via OAuth

The recommended way to authenticate is via OAuth: your browser opens, you log in with your DatoCMS account, and the CLI stores credentials locally. No tokens to copy and paste.

Terminal window

```bash
npx datocms login
```

Credentials are saved to `~/.config/datocms/credentials.json`. You can verify your identity at any time:

Terminal window

```bash
npx datocms whoami
```

`whoami` is also useful as a quick health-check that the CLI is set up correctly; coding agents tend to call it as the first step when operating on an unfamiliar repo.

## Link the current directory to a project

Linking generates a `datocms.config.json` configuration file in the current directory and avoids having to repeat options for every command you run:

```plaintext
$ npx datocms link

✔ Choose a workspace › My organization
✔ Search and select a project › My project
✔ Directory where script migrations will be stored ./migrations
✔ API key of the DatoCMS model used to store migration data schema_migration
Writing "datocms.config.json"... done
```

Once linked, every CLI command in this directory automatically resolves an API token for the linked project using your OAuth credentials. No need to set environment variables.

The generated `datocms.config.json` file will look similar to this:

```json5
{
  "profiles": {
    "default": {
      "logLevel": "NONE",
      "siteId": "12345", // The linked DatoCMS project ID
      "organizationId": "67890", // The organization the project belongs to
      "migrations": {
        "directory": "./migrations",
        "modelApiKey": "schema_migration",
        "template": "",
        "tsconfig": ""
      }
    }
  }
}
```

Add the config file to your Git repository so your collaborators and CI pipelines can reuse it:

Terminal window

```bash
git add datocms.config.json
git commit -m "Add datocms.config.json file"
```

> [!PROTIP] Pro tip: Need to manage multiple DatoCMS projects from the same repo?
> You can set up additional profiles with `datocms link --profile=<NEW_PROFILE_NAME>`, then specify which profile to use with the `--profile` flag (or by setting a `DATOCMS_PROFILE` environment variable). See [Profiles and multi-project setup](https://www.datocms.com/docs/cli/profiles-and-multi-project-setup.md) for the full picture.

## 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)