# Data transfer

> Source: https://docs.strapi.io/cms/features/data-management/transfer

The `strapi transfer` command streams data between two Strapi instances with identical schemas, transferring content, files, and configuration using transfer tokens for authorization and authentication.

The `strapi transfer` command is part of the [Data Management feature](/cms/features/data-management) and streams your data from one Strapi instance to another Strapi instance. The `transfer` command uses strict schema matching, meaning your two Strapi instances need to be exact copies of each other except for the contained data. The default `transfer` command transfers your content (entities and relations), files (assets), project configuration, and schemas. The command allows you to transfer data:

- from a local Strapi instance to a remote Strapi instance
- from a remote Strapi instance to a local Strapi instance

The following documentation details the available options to customize your data transfer. The transfer command and all of the available options are run using the [Strapi CLI](/cms/cli#strapi-transfer).

:::caution

* If you are using an SQLite database in the destination instance other database connections will be blocked while the `transfer` operation is running.
* Admin users and API tokens are not transferred.
* If you use websockets or Socket.io in your projects, the transfer command will fail. You will need to **temporarily disable websockets or Socket.io** or ensure that your websocket server is running on a different port than the Strapi server, or a on a specific route within Strapi to use the transfer command.

:::

The CLI command consists of the following arguments:

| Option         | Description                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--to`         | Full URL of the `/admin` endpoint on the destination Strapi instance<br />(e.g. `--to https://my-beautiful-strapi-website/admin`)            |
| `‑‑to‑token`   | Transfer token from the Strapi destination instance.                                                                                         |
| `--from`       | Full URL of the `/admin` endpoint of the remote Strapi instance to pull data from (e.g., `--from https://my-beautiful-strapi-website/admin`) |
| `‑‑from‑token` | Transfer token from the Strapi source instance.                                                                                              |
| `--force`      | Automatically answer "yes" to all prompts, including potentially destructive requests, and run non-interactively.                            |
| `--exclude`    | Exclude data using comma-separated data types. The available types are: `content`, `files`, `config`, and `media-library` (excludes both upload binaries and upload content type records). |
| `--only`       | Include only these data. The available types are: `content`, `files`, and `config`.                                                          |
| `--exclude-content-types` | Comma-separated list of content-type UIDs to exclude. Both entity records and relation links touching an excluded type are skipped. |
| `--only-content-types` | Comma-separated list of content-type UIDs to include. Only entity records and relation links for the listed types are transferred. |
| `--throttle` | Time in milliseconds to inject an artificial delay between the "chunks" during a transfer. |
| `--no-checksums` | Disable end-to-end SHA-256 checksum verification for assets. Checksum verification is enabled by default when both the source and destination instances support it. |
| `--verbose` | Enable verbose logs. |

:::caution
Either `--to` or `--from` is required.
:::

:::tip Tips
* Data transfers are authorized by transfer tokens, which are [managed from the admin panel](/cms/features/data-management#admin-panel-settings). From the admin panel, you can manage role-based permissions to tokens including `view`, `create`, `read`, `regenerate` and `delete`.
* It might be convenient to store your transfer tokens into [environment variables](/cms/configurations/environment) to avoid copying/pasting. Just ensure that these tokens are not pushed to public repositories.
:::

:::warning
When using nginx and a server that proxies requests into a localhost, issues might occur. To prevent them, ensure all the headers are forwarded correctly by changing the configuration file in `/etc/nginx/sites-available/yourdomain` as follows:

```
server {
    listen 80;
    server_name <yourdomain>;
    location / {
        proxy_pass http://localhost:1337;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        include proxy_params;
    }
}
```

:::

## Generate a transfer token

:::prerequisites
A salt transfer token should be defined in the [admin panel configuration](/cms/configurations/admin-panel) file.
:::

The `strapi transfer` command requires a transfer token issued by the destination instance. To generate a transfer token in the admin panel use the instructions in the [User Guide](/cms/features/data-management#admin-panel-settings).

## Setup and run the data transfer

Initiating a data transfer depends on whether you want to push data to a remote instance or to pull data from the remote:

1. Start the Strapi server for the destination instance.
  2. In a new terminal window, navigate to the root directory of the source instance.
  3. Run the following minimal command to initiate the transfer, ensuring `destinationURL` is the full URL to the admin panel (i.e., the URL includes the `/admin` part):

    ```bash
    yarn strapi transfer --to destinationURL
    ```

    ```bash
    npm run strapi transfer -- --to destinationURL
    ```
  
  4. Add the transfer token when prompted to do so.
  5. Answer **Yes** or **No** to the CLI prompt: "The transfer will delete all of the remote Strapi assets and its database. Are you sure you want to proceed?"

1. Start the Strapi server for the source instance.
2. In a new terminal window, navigate to the root directory of the destination instance.
  3. Run the following minimal command to initiate the transfer, ensuring `remoteURL` is the full URL to the admin panel (i.e., the URL includes the `/admin` part):

  ```bash
  yarn strapi transfer --from remoteURL
  ```

  ```bash
  npm run strapi transfer -- --from remoteURL
  ```

4. Add the transfer token when prompted to do so.
5. Answer **Yes** or **No** to the CLI prompt: "The transfer will delete all of the local Strapi assets and its database. Are you sure you want to proceed?".

Once the transfer starts, the command reports live progress in the terminal, including preparation steps, per-stage progress, and timing with an estimated time remaining.

## Bypass all `transfer` command line prompts

When using the `strapi transfer` command, you are required to confirm that the transfer will delete the existing database contents. The `--force` flag allows you to bypass this prompt. This option is useful for implementing `strapi transfer` programmatically. You must pass the `to-token` option with the transfer token if you use the `--force` option.

:::caution
The `--force` option bypasses all warnings about content deletion.
:::

### Example: bypass the `transfer` command line prompts with `--force`

```bash
yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token --force
```

```bash
npm run strapi transfer -- --to https://example.com/admin --to-token my-transfer-token --force
```

## Include only specified data types during transfer

The default `strapi transfer` command transfers your content (entities and relations), files (assets), project configuration, and schemas. The `--only` option allows you to transfer only the listed items by passing a comma-separated string with no spaces between the types. The available values are `content`, `files`, and `config`. Schemas are always transferred, as schema matching is used for `strapi transfer`.

### Example: only transfer files

```bash
yarn strapi transfer --to https://example.com/admin --only files
```

```bash
npm run strapi transfer -- --to https://example.com/admin --only files
```

## Exclude data types during transfer

The default `strapi transfer` command transfers your content (entities and relations), files (assets), project configuration, and schemas. The `--exclude` option allows you to exclude content, files, and the project configuration by passing these items in a comma-separated string with no spaces between the types. You can't exclude the schemas, as schema matching is used for `strapi transfer`.

### Example: exclude files from transfer

```bash
yarn strapi transfer --to https://example.com/admin --exclude files
```

```bash
npm run strapi transfer -- --to https://example.com/admin --exclude files
```

:::warning
Any types excluded from the transfer will be deleted in your destination instance. For example, if you exclude `config` the project configuration in your destination instance will be deleted.
:::

## Filter content types during transfer

The `--exclude-content-types` and `--only-content-types` options let you scope a transfer to specific content types. Both options accept a comma-separated list of content-type UIDs (for example, `api::article.article`). Unknown UIDs are validated against the Strapi schema at startup. Both entity records and any relation links touching an excluded type are skipped automatically.

:::warning Warning: Restore behavior
- When you use `--exclude-content-types`, data for the excluded types is **preserved** on the destination — they are not wiped before the transfer.
- When you use `--only-content-types`, the pre-transfer wipe is scoped to only the listed UIDs, leaving all other content on the destination in place.
:::

### Exclude specific content types from transfer

```bash
yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token \
  --exclude-content-types api::article.article
```

```bash
npm run strapi transfer -- --to https://example.com/admin --to-token my-transfer-token \
  --exclude-content-types api::article.article
```

### Transfer only specific content types

```bash
yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token \
  --only-content-types api::article.article,api::category.category
```

```bash
npm run strapi transfer -- --to https://example.com/admin --to-token my-transfer-token \
  --only-content-types api::article.article,api::category.category
```

## Manage data transfer with environment variables

The environment variable `STRAPI_DISABLE_REMOTE_DATA_TRANSFER` is available to disable remote data transfer. In addition to the [RBAC permissions](/cms/features/rbac#plugins-and-settings) in the admin panel this can help you secure your Strapi application. To use `STRAPI_DISABLE_REMOTE_DATA_TRANSFER` you can add it to your `.env` file or preface the `start` script. See the following example:

```bash
STRAPI_DISABLE_REMOTE_DATA_TRANSFER=true yarn start
```

Additional details on using environment variables in Strapi are available in the [Environment configurations documentation](/cms/configurations/environment).

## Test the transfer command locally

The `transfer` command is not intended for transferring data between two local instances. The [`export`](/cms/features/data-management/export) and [`import`](/cms/features/data-management/import) commands were designed for this purpose. However, you might want to test `transfer` locally on test instances to better understand the functionality before using it with a remote instance. The following documentation provides a fully-worked example of the `transfer` process.

### Create and clone a new Strapi project

1. Create a new Strapi project using the installation command:

   ```bash
   npx create-strapi-app@latest <project-name> --quickstart
   ```

2. Create at least 1 content type in the project. See the [Quick Start Guide](/cms/quick-start) if you need instructions on creating your first content type.

   :::caution
   Do not add any data to your project at this step.
   :::

3. Commit the project to a git repository:

   ```bash
   git init
   git add .
   git commit -m "first commit"
   ```

4. Clone the project repository:

   ```bash
   cd .. # move to the parent directory
   git clone <path to created git repository>.git/ <new-instance-name>
   ```

5. Move into the cloned project and install its dependencies:

```bash
cd <new-instance-name>
yarn install
```
```bash
cd <new-instance-name>
npm install
```

   Without this step, the next `build` and `start` commands fail because `strapi` is not yet on the project's local executable path.

### Add data to the first Strapi instance

1. Return to the first Strapi instance and add data to the content type.
2. Stop the server on the first instance.

### Create a transfer token

1. Navigate to the second Strapi instance and run the `build` and `start` commands in the root directory:

```bash
yarn build && yarn start
```

```bash
npm run build && npm run start
```

2. Register an admin user.
3. [Create and copy a transfer token](/cms/features/data-management#admin-panel-settings).
4. Leave the server running.

### Transfer your data

1. Return the the first Strapi instance.
2. In the terminal run the `strapi transfer` command:

```bash
yarn strapi transfer --to http://localhost:1337/admin
```

```bash
npm run strapi transfer -- --to http://localhost:1337/admin
```

3. When prompted, apply the transfer token.
4. When the transfer is complete you can return to the second Strapi instance and see that the content is successfully transferred.

:::tip
In some cases you might receive a connection refused error targeting `localhost`. Try changing the address to [http://127.0.0.1:1337/admin](http://127.0.0.1:1337/admin).
:::