From aa2f39d9b3ee33f22583cf2983eee56f72ec528a Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 02:23:12 +0000 Subject: [PATCH] Document --exclude-content-types and --only-content-types for data management Add new sections to export, import, and transfer pages covering the --exclude-content-types and --only-content-types CLI flags. Update the CLI reference tables for strapi export, import, and transfer, including the media-library shorthand for --exclude. Based on strapi/strapi#26915. --- docusaurus/docs/cms/cli.md | 10 ++- docusaurus/docs/cms/data-management/export.md | 74 +++++++++++++++++++ docusaurus/docs/cms/data-management/import.md | 55 ++++++++++++++ .../docs/cms/data-management/transfer.md | 63 +++++++++++++++- 4 files changed, 199 insertions(+), 3 deletions(-) diff --git a/docusaurus/docs/cms/cli.md b/docusaurus/docs/cms/cli.md index f773065f38..220049200f 100644 --- a/docusaurus/docs/cms/cli.md +++ b/docusaurus/docs/cms/cli.md @@ -227,8 +227,10 @@ The exported file is automatically named using the format `export_YYYYMMDDHHMMSS | `-k`,
`--key` | string | Passes the encryption key as part of the `export` command.
The `--key` option can't be combined with `--no-encrypt`. | | `-f`,
`--file` | string | Specifies the export filename (tar) or output directory path (dir). Do not include a file extension for tar exports. | | `--format` | string | Export format: `tar` (default) or `dir`. Directory exports require `--no-encrypt`. | -| `--exclude` | string | Exclude data using comma-separated data types. The available types are: `content`, `files`, and `config`. | +| `--exclude` | string | 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` | string | Include only these data. The available types are: `content`, `files`, and `config`. | +| `--exclude-content-types` | string | Comma-separated list of content-type UIDs to exclude from the export. Both entity records and relation links are excluded. | +| `--only-content-types` | string | Comma-separated list of content-type UIDs to include in the export. | | `-h`,
`--help` | - | Displays help for the `strapi export` command. | **Examples** @@ -265,6 +267,8 @@ The command accepts archives generated by `strapi export` (`.tar`, `.tar.gz`, `. | -------------- | ------ | ------------------------------------------------------------------------------------- | | `-k,` `--key` | string | Provide the encryption key in the command instead of a subsequent prompt. | | `-f`, `--file` | string | Path to a `.tar[.gz][.enc]` archive or to an unpacked export directory. | +| `--exclude-content-types` | string | Comma-separated list of content-type UIDs to exclude from the import. Excluded types are preserved on the destination. | +| `--only-content-types` | string | Comma-separated list of content-type UIDs to include in the import. | | `-h`, `--help` | - | Display the `strapi import` help commands. | **Examples** @@ -296,8 +300,10 @@ The destination Strapi instance should be running with the `start` command and n | `--from [sourceURL]` | 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`, and `config`. | +| `--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 are excluded. | +| `--only-content-types` | Comma-separated list of content-type UIDs to include. Only entity records and relation links for the listed types are transferred. | | `-h`, `--help` | Displays the commands for `strapi transfer`. | :::caution diff --git a/docusaurus/docs/cms/data-management/export.md b/docusaurus/docs/cms/data-management/export.md index 7a4211edc5..c03400310a 100644 --- a/docusaurus/docs/cms/data-management/export.md +++ b/docusaurus/docs/cms/data-management/export.md @@ -312,4 +312,78 @@ npm run strapi export -- --exclude files,content +## Filter content types during export + + + +The `--exclude-content-types` and `--only-content-types` options let you scope an export 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. + +### Exclude specific content types + + + + + +```bash +yarn strapi export --exclude-content-types api::article.article +``` + + + + + +```bash +npm run strapi export -- --exclude-content-types api::article.article +``` + + + + + +### Export only specific content types + + + + + +```bash +yarn strapi export --only-content-types api::article.article,api::category.category +``` + + + + + +```bash +npm run strapi export -- --only-content-types api::article.article,api::category.category +``` + + + + + +### Exclude the entire media library + +To exclude both the upload binaries and the upload content type records, pass `media-library` to the `--exclude` flag. This is equivalent to combining `--exclude files` with `--exclude-content-types plugin::upload.file,plugin::upload.folder`: + + + + + +```bash +yarn strapi export --no-encrypt --exclude media-library +``` + + + + + +```bash +npm run strapi export -- --no-encrypt --exclude media-library +``` + + + + + diff --git a/docusaurus/docs/cms/data-management/import.md b/docusaurus/docs/cms/data-management/import.md index 0c916090f9..54cbbb091d 100644 --- a/docusaurus/docs/cms/data-management/import.md +++ b/docusaurus/docs/cms/data-management/import.md @@ -278,4 +278,59 @@ npm strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --only +## Filter content types during import + + + +The `--exclude-content-types` and `--only-content-types` options let you scope an import 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. + +:::warning Restore behavior +- When you use `--exclude-content-types`, data for the excluded types is **preserved** on the destination — the import does not wipe those records before restoring. +- When you use `--only-content-types`, the pre-import wipe is scoped to only the listed UIDs, leaving all other content in place. +::: + +### Exclude specific content types from import + + + + + +```bash +yarn strapi import -f export_20221213105643.tar.gz.enc --exclude-content-types api::article.article +``` + + + + + +```bash +npm run strapi import -- -f export_20221213105643.tar.gz.enc --exclude-content-types api::article.article +``` + + + + + +### Import only specific content types + + + + + +```bash +yarn strapi import -f export_20221213105643.tar.gz.enc --only-content-types api::article.article,api::category.category +``` + + + + + +```bash +npm run strapi import -- -f export_20221213105643.tar.gz.enc --only-content-types api::article.article,api::category.category +``` + + + + + diff --git a/docusaurus/docs/cms/data-management/transfer.md b/docusaurus/docs/cms/data-management/transfer.md index 9f6c570c4e..a231453b92 100644 --- a/docusaurus/docs/cms/data-management/transfer.md +++ b/docusaurus/docs/cms/data-management/transfer.md @@ -44,8 +44,10 @@ The CLI command consists of the following arguments: | `--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`, and `config`. | +| `--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. | @@ -243,6 +245,65 @@ npm run strapi transfer -- --to https://example.com/admin --exclude files 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 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: