Data transfer

Page summary:

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

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.
• The command fails if your project uses websockets or Socket.io. See Troubleshooting.

The CLI command consists of the following arguments:

Option	Description
--to	Full URL of the /admin endpoint on the destination Strapi instance (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 each transferred entity.
--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.

Either --to or --from is required.

Tip

It might be convenient to store your transfer tokens into environment variables to avoid copying/pasting. Just ensure that these tokens are not pushed to public repositories.

Generate a transfer token

Prerequisites

A salt transfer token should be defined in the admin panel configuration 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.

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:

Push data to 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):

yarn

terminal

yarn strapi transfer --to destinationURL

npm

terminal

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 existing data from the remote Strapi! Are you sure you want to proceed?"

Pull data from remote

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

yarn

terminal

yarn strapi transfer --from remoteURL

npm

terminal

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

What a transfer replaces and preserves

5.52.2The preserve-versus-replace behavior described below is clarified and logged by the CLI since Strapi 5.52.2.

When you use --only or --exclude, only the stages you name are affected on the destination:

• Omitted stages are preserved. When a stage is not transferred, the destination data for that stage is left untouched.
• Transferred stages are replaced. Any stage you include in the transfer fully replaces the destination data for that stage, except for admin types and ignored types such as plugin::content-releases.release, which are always preserved.

Stage filtering and content-type filtering are independent and can be combined. Stage filters (--only and --exclude) select which kinds of data move. Content-type filters (--only-content-types and --exclude-content-types) narrow which content types move within the content stage.

Example: refresh content while preserving destination config

To refresh only content from a source instance while keeping the destination instance's configuration:

yarn

terminal

yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token --only content

npm

terminal

npm run strapi transfer -- --to https://example.com/admin --to-token my-transfer-token --only content

Each preset maps to transfer stages: content covers entities and links, meaning content-type rows, including media library database records, and their relations. files covers the assets stage, meaning the upload binaries under public/uploads. config covers the core store and webhooks. Schemas are always transferred, independently of these presets.

Caution

Media is split across two presets. The files preset covers only the binaries, while the media library database records (plugin::upload.file and plugin::upload.folder) belong to content. So --exclude files alone only skips the assets stage: the records still transfer, and the destination can end up with records pointing to binaries that were never transferred. To preserve both, use --exclude media-library.

Flags	Transferred	Preserved on the destination
Default strapi transfer	Content, files, config	Admin and ignored types only
--only content	Content	Config and upload binaries
--only files	Files	Content and config
--only config	Config	Content and files
--only content,files	Content and files	Config
--exclude content	Files and config	Content
--exclude files	Content and config	Upload binaries
--exclude media-library	Content without upload types, and config	Upload binaries, plugin::upload.file, and plugin::upload.folder

Transfer only or exclude data types

The default strapi transfer command transfers your content (entities and relations), files (assets), project configuration, and schemas. Two options let you narrow that scope by passing a comma-separated string with no spaces between the types:

• --only transfers only the listed items. The available values are content, files, and config.
• --exclude leaves out the listed items. The available values are content, files, config, and media-library, which excludes both the upload binaries and the upload content-type records.

Schemas can never be excluded, as schema matching is used for strapi transfer.

Example: only transfer files

yarn

terminal

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

npm

terminal

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

Example: exclude files from transfer

yarn

terminal

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

npm

terminal

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

Filter content types during transfer

5.50.3This feature requires Strapi version 5.50.3 or later.

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

yarn

terminal

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

npm

terminal

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

yarn

terminal

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

npm

terminal

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

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. The deletion only covers the stages that are actually transferred: if you filter stages with --only or --exclude, the omitted stages are preserved. See What a transfer replaces and preserves.

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

yarn

terminal

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

npm

terminal

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

Tune transfer performance and verification

Three options adjust how a transfer runs rather than what it carries:

• --no-checksums disables the end-to-end SHA-256 checksum verification applied to assets. Verification is enabled by default whenever both the source and the destination support it, and it is what guarantees that assets arrive intact, so disable it only when you are troubleshooting.
• --throttle injects an artificial delay, in milliseconds, between each transferred entity. Use it to reduce the load a large transfer puts on the destination.
• --verbose prints detailed logs, which is useful when a transfer fails without an obvious cause.

Asset transfers also depend on the transfer.remote.assetIdleTimeoutMs server option, which sets how long an idle asset stream may stay open before the transfer aborts. See the server configuration documentation.

Example: throttle a transfer and disable checksum verification

yarn

terminal

yarn strapi transfer --to https://example.com/admin --to-token my-transfer-token \
  --throttle 100 --no-checksums

npm

terminal

npm run strapi transfer -- --to https://example.com/admin --to-token my-transfer-token \
  --throttle 100 --no-checksums

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

terminal

STRAPI_DISABLE_REMOTE_DATA_TRANSFER=true yarn start

Additional details on using environment variables in Strapi are available in the Environment configurations documentation.

Troubleshooting

A transfer behind an nginx reverse proxy fails. When nginx proxies requests into a localhost, the transfer can fail if headers are not forwarded. 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;
    }
}

A connection is refused when targeting localhost. Try changing the address to http://127.0.0.1:1337/admin.

The transfer fails and the project uses websockets. The transfer command fails when websockets or Socket.io are in use. Temporarily disable them, or ensure the websocket server runs on a different port than the Strapi server, or on a specific route within Strapi.

Practice before transferring to a remote instance

Test a data transfer locally

Run through the whole transfer workflow between two local instances first.