> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

# Updating Cross-space references using the Contentful CLI

> This guide will help you update Cross-space references using the Contentful CLI.

There are two ways users can review which spaces and environments are using cross-space links and which links should be updated:

1. Exporting contents of every space using [`contentful-export`](https://github.com/contentful/contentful-cli/blob/master/docs/space/export/README.md) and [`contentful-import`](https://github.com/contentful/contentful-cli/blob/master/docs/space/import/README.md).
2. Creating custom migration scripts.

## 1. Export contents of a space

When exporting the contents of a space, follow these steps:

1. Export contents of a single space using the following command: `contentful space export`.
   The resulting `.json` file contains all the information about the space. The important properties are the `contentTypes` and `entries`.

```json
{
  "contentTypes": [
    {
      "sys": {
        "space": {
          "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "space-a-id"
          }
        },
        "id": "restaurant",
        "type": "ContentType"
      },
      "displayField": "name",
      "name": "Restaurant",
      "description": "",
      "fields": [
        {
          "id": "name",
          "name": "Name",
          "type": "Symbol"
        },
        {
          "id": "menu",
          "name": "Menu",
          "type": "Array",
          "items": {
            "type": "ResourceLink",
            "validations": []
          },
          "allowedResources": [
            {
              "type": "Contentful:Entry",
              "source": "crn:contentful:::content:spaces/space-b-id/environments/master",
              "contentTypes": ["dish"]
            }
          ]
        },
        {
          "id": "about",
          "name": "About",
          "type": "RichText",
          "validations": [
            {
              "enabledMarks": [],
              "message": "Marks are not allowed"
            },
            {
              "enabledNodeTypes": ["embedded-resource-block"],
              "message": "Only block entry from a different space nodes are allowed"
            },
            {
              "nodes": {
                "embedded-resource-block": {
                  "validations": [],
                  "allowedResources": [
                    {
                      "type": "Contentful:Entry",
                      "source": "crn:contentful:::content:spaces/space-b-id/environments/master",
                      "contentTypes": ["address"]
                    }
                  ]
                }
              }
            }
          ]
        }
      ]
    }
  ],
  "entries": [
    {
      "sys": {
        "space": {
          "sys": {
            "type": "Link",
            "linkType": "Space",
            "id": "space-a-id"
          }
        },
        "id": "5gDrXf0Nf223qHTWNnxNwn",
        "type": "Entry",
        "environment": {
          "sys": {
            "id": "master",
            "type": "Link",
            "linkType": "Environment"
          }
        },
        "contentType": {
          "sys": {
            "type": "Link",
            "linkType": "ContentType",
            "id": "restaurant"
          }
        }
      },
      "fields": {
        "name": {
          "en-US": "My favorite pizza place"
        },
        "menu": {
          "en-US": [
            {
              "sys": {
                "type": "ResourceLink",
                "linkType": "Contentful:Entry",
                "urn": "crn:contentful:::content:spaces/space-b-id/environments/master/entries/dish-1-id"
              }
            },
            {
              "sys": {
                "type": "ResourceLink",
                "linkType": "Contentful:Entry",
                "urn": "crn:contentful:::content:spaces/space-b-id/environments/master/entries/dish-2-id"
              }
            }
          ]
        },
        "about": {
          "en-US": {
            "content": [
              {
                "content": [
                  {
                    "value": "This is my favorite pizza restaurant!",
                    "nodeType": "text"
                  }
                ],
                "nodeType": "paragraph"
              },
              {
                "data": {
                  "target": {
                    "sys": {
                      "urn": "crn:contentful:::content:spaces/space-b-id/environments/master/entries/4vxXfphlVtXmbyvMsnL4U9",
                      "type": "ResourceLink",
                      "linkType": "Contentful:Entry"
                    }
                  }
                },
                "nodeType": "embedded-resource-block"
              }
            ],
            "nodeType": "document"
          }
        }
      }
    }
  ]
}

```

2. Analyze the members of the `contentTypes` array and their `.fields` property. Identify all fields that contain array `allowedResources`. Be aware it can be both fields of type `ResourceLink`, as well as `RichText`.

3. For each element of collected `allowedResources`, inspect its source property containing the definition of allowed cross-space links. Investigate which of these are relevant to your use case and update their environments segment accordingly.

If the link does not contain the environment segment, it means it is implicitly pointing to a master environment. You can still add the explicit segment following this format: `crn:contentful:::content:spaces/<space-id>/environments/<environment-id>`.

4. Analyze the members of entries array and their `.fields` property. Identify all fields that contain `urn` property and are of content type that you have adjusted in previous steps. Update the `urn` accordingly, by adding the `environments` segment.

5. Once you are done with editing, you can import changed json file and apply changes to the space: `contentful space import –content-file name-of-json-file.json`.

6. Repeat all these steps for all linked spaces.

**IMPORTANT**: This approach recreates the modified entries (possibly losing versioning / history?). For more information, see [Importing to a space with existing content](https://github.com/contentful/contentful-import#bulb-importing-to-a-space-with-existing-content).

## 2. Create a custom migration script

The Merge CLI allows users to run migrations, which can be a combination of scripts generated by CLI and modifications implemented by the users. By running the command `contentful merge export --te <source-environment> --se <target-environment>`, users can generate a base migration script editing the content model. This base migration script can be further enhanced to apply necessary changes, as well to add transformations for entries. For more information about this, see:

* [documentation on `transformEntries()` method](https://github.com/contentful/contentful-migration/tree/master#transformentriesconfig)
* [example usage](https://github.com/contentful/contentful-migration/blob/6494cd9d0e799127873318fbf5aa6aeb7fb5ef77/examples/12-transform-content.js#L5)

In addition, you can use the Content Management API to [update content models](/references/content-management-api/overview) and [update entries](/references/content-management-api/overview).

> This guide will help you update Cross-space references using the Contentful CLI.