The CLI tool includes the following commands for working with content:
Content Item Commands: dc-cli content-item archive [id] Archive Content Items dc-cli content-item copy Copy content items. The active account and hub are the source for the copy. dc-cli content-item export <dir> Export Content Items dc-cli content-item import <dir> Import content items dc-cli content-item move Move content items. The active account and hub are the source for the move. dc-cli content-item tree <dir> Print a content dependency tree from content in the given folder. dc-cli content-item unarchive [id] Unarchive Content Items Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean]
The following example shows how to copy content from two of the hubs you have set up. It should be noted that you can also copy content from one repository to another in the same hub.
info
Remember that when you copy items you must also export and import the associated schema and content types.
To begin, we want to copy the content to the destination without removing it from the source hub, so we'll use copy:
Copy content items. The active account and hub are the source for the copy. Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean] --revertLog Path to a log file to revert a copy for. This will archive the most recently copied resources, and revert updated ones. [string] --srcRepo Copy content from within a given repository. Directory structure will start at the specified repository. Will automatically export all contained folders. [string] --srcFolder Copy content from within a given folder. Directory structure will start at the specified folder. Can be used in addition to repoId. [string] --dstRepo Copy matching the given repository to the source base directory, by ID. Folder structure will be followed and replicated from there. [string] --dstFolder Copy matching the given folder to the source base directory, by ID. Folder structure will be followed and replicated from there. [string] --dstHubId Destination hub ID. If not specified, it will be the same as the source. [string] --dstClientId Destination account's client ID. If not specified, it will be the same as the source. [string] --dstSecret Destination account's secret. Must be used alongside dstClientId. [string] --facet Copy content matching the given facets. Provide facets in the format 'label:example name,locale:en-GB', spaces are allowed between values. A regex can be provided for text filters, surrounded with forward slashes. For more examples, see the readme. [string] --mapFile Mapping file to use when updating content that already exists. Updated with any new mappings that are generated. If not present, will be created. [string] -f, --force Overwrite content, create and assign content types, and ignore content with missing types/references without asking. [boolean] -v, --validate Only recreate folder structure - content is validated but not imported. [boolean] --skipIncomplete Skip any content item that has one or more missing dependancy. [boolean] --lastPublish When available, export the last published version of a content item rather than its newest version. [boolean] --publish Publish any content items that either made a new version on import, or were published more recently in the JSON. [boolean] --batchPublish Batch publish requests up to the rate limit. (35/min) [boolean] --republish Republish content items regardless of whether the import changed them or not. (--publish not required) [boolean] --excludeKeys Exclude delivery keys when importing content items.[boolean] --media Detect and rewrite media links to match assets in the target account's DAM. Your client must have DAM permissions configured. [boolean] --logFile Path to a log file to write to. [string] [default: (generated-value)]
The source folder is called "CLI tool content" and has an id of 648831b9147e044acb973583 in the "Amp Doc Examples" hub. To find the folder id use the Content Management API, as explained in the finding folder IDs section.
This content will be copied into the "CLI tester folder" in the "Amp Docs Hub" that has an id of 64a3e079c5d8d7697391414a.
We also want to publish any content item that was published on the source hub so we'll use specify the "--publish" option.
The copy command is as shown below. The destination hub ID must be specified and we assume that the clientID, secret and source hub are specified in the configuration file:
After running the copy command the following output is shown in the command line.
=== Exporting from source... === Retrieving content items, please wait. Found 1 base folders. Processing ... Fetching additional folder: CLI tool content Scanning for dependancies. Saving content items. /Users/kojogbede/.amplience/copy-1688513127224/CLI tool text.json /Users/kojogbede/.amplience/copy-1688513127224/CLI tool image.json /Users/kojogbede/.amplience/copy-1688513127224/CLI tool author.json /Users/kojogbede/.amplience/copy-1688513127224/Autumn banner.json /Users/kojogbede/.amplience/copy-1688513127224/CLI tool banner.json === Importing to destination... === Creating new mapping file at '/Users/username/.amplience/imports/folder-64a3e079c5d8d7697391414a.json'. Scanning structure and content in '/Users/username/.amplience/copy-1688513127224/' for repository 'Content'... Done. Validating content... Importing 5 content items... Creating circular dependants. Resolving circular dependants. Publishing 5 items. (0 children included) Started publish for Autumn banner. Started publish for CLI tool text. Started publish for CLI tool author. Started publish for CLI tool banner. Started publish for CLI tool image. Waiting for all publishes to complete... Finished publishing, with 0 failed publishes total. Done! === Done! ===
The items have been copied to the "CLI tester folder" in the "Amp Docs Hub" and have all been published.
Copying items between different accounts
The --media command allows you to copy between hubs on different content hub accounts. Before using --media, make sure there are matching files existing on both content hub accounts. To do this, you can import all the same assets into your destination hub either via an external process like an ftp upload, or you can manually upload them using Content Hub.
There are some useful options available when you copy, move or import content items from one location to another.
When you run a dc-cli content-item copy or dc-cli content-item move command, a log file is created containing a list of the content items that were copied or moved. This file is stored locally in the ".amplience/logs" folder. The log file can be specified in the -revert parameter to undo a copy or move, archiving the content items on the destination.
--revertLog Path to a log file to revert a copy for. This will archive the most recently copied resources, and revert updated ones.
You can revert the folder copy example by specifying the log file generated from the original copy:
Archiving Blue dress slide. Archiving Get ready for summer. Archiving Sunglasses slide. Archiving Hat slide. Archiving Bright colours slide. Archiving Summer carousel. Done! Log written to "/Users/userName/.amplience/logs/item-copy-1612481700095.log".
The items that were copied to the destination are now archived.
A mapping file is generated when you run a copy, import or clone command. This file is created in the ".amplience/imports" folder and contains the content ids of the content items on the source and destination. The content ids for the source and destination are presented in JSON format as an array of arrays. An example mapping file is shown below:
The cli-tool will attempt to load a mapping file when it is run. For example if you are copying from one folder to another, by default it will look for a mapping file labeled with the source folder id in the .amplience/imports directory. If a mapping file cannot be found, then new content items will be created in the destination.
--mapFile Mapping file to use when updating content that already exists. Updated with any new mappings that are generated. If not present, will be created. [string]
If you want to include your own mapping file while using performing an import, clone or copy, the command would be:
--mapFile [path to mapping file document]
Using —-mapFile to include an existing mapping file is recommended, as this avoids any duplicate content being made.
Example: Updating content locally with an existing mapping file
When you run a copy, clone or import command and an existing mapping file is used, you can choose whether to update existing content items or not.
In the example below, we are asked whether we would like to existing some items that already exist in the mapping file when we repeat the copy command used in the folder copy example.
We are given this option because a mapping file already exists that includes some of the content items we'd like to import. This means that we can choose to either update or leave them as they are:
=== Exporting from source... === Retrieving content items, please wait. Found 1 base folders. Processing ... Fetching additional folder: CLI tool content Scanning for dependancies. Saving content items. /Users/kojogbede/.amplience/copy-1688514570584/CLI tool text.json /Users/kojogbede/.amplience/copy-1688514570584/CLI tool image.json /Users/kojogbede/.amplience/copy-1688514570584/CLI tool author.json /Users/kojogbede/.amplience/copy-1688514570584/Autumn banner.json /Users/kojogbede/.amplience/copy-1688514570584/CLI tool banner.json === Importing to destination... === Existing mapping loaded from '/Users/kojogbede/.amplience/imports/folder-64a3e079c5d8d7697391414a.json', changes will be saved back to it. Scanning structure and content in '/Users/kojogbede/.amplience/copy-1688514570584/' for repository 'Content'... Done. Validating content... 5 of the items being imported already exist in the mapping. Would you like to update these content items instead of skipping them? (y/n) y Found 1 dependancy levels in 5 items, 0 referencing a circular dependancy. Importing 5 content items... Creating circular dependants. Resolving circular dependants. Publishing 5 items. (0 children included) Started publish for Autumn banner. Started publish for CLI tool text. Started publish for CLI tool author. Started publish for CLI tool banner. Started publish for CLI tool image. Waiting for all publishes to complete... Finished publishing, with 0 failed publishes total. Done! === Done! ===
Generating mapping files when migrating across multiple hubs
When migrating content between hubs, by default the CLI tool will try to create the migrated content based on the hub ID provided. Due to this being considered new content, a different mapping file will be created for the content copied to each hub.
In this example a mapping file is generated when we copy content in a specific folder from the source folder "CLI tool content" in the "Amp Doc Examples" hub into the "CLI tester folder" in the "Amp Docs Hub".
Copying content within a single hub works in a similar way to migrating content across different hubs. You need the folder id of the folder you'd like to copy your content to, as well as the hub id.
If you don't have your credentials saved in a config file, you will need to include the client id and client secret associated with your hub in the command.
A new mapping file will be generated by default when the content is copied into the new folder as this is considered new content, despite being in the same hub. If you were to copy into multiple folders, as explained above, multiple mapping files would be generated.
Workflow states: how mapping files work with settings
Workflow states (also referred to as content statuses) are tags that you can assign to content items. You can apply one workflow state to a content item at a time, and set them up from the status menu in your hub settings.
note
Currently you cannot delete content statuses once you create them. You can only re-label them.
A workflow state is identified by its id. When you export settings from one hub and import to another (without specifying an existing mapping file), ids will be generated for each of the workflow states exported from the source hub. A mapping file will be created containing the workflow states exported from the source hub, and the ids of the corresponding workflow states imported to the destination hub.
Below is an example of a mapping file with workflow state ids for a source and destination hub:
When you import these settings into another hub, the workflow state from the source hub is mapped to the corresponding workflow state in the destination hub. If you import settings again using an existing mapping file, then you can update existing workflow states and prevent duplication. This is particularly useful because workflow states cannot be deleted from a hub.
This example shows how to export all the content items in a folder called "Collections" in the "Content" repository on our "Documentation" hub to a local folder.
To find the commands available for content items, type the following in your command line:
dc-cli content-item --help
Content Item Commands: dc-cli content-item archive [id] Archive Content Items dc-cli content-item copy Copy content items. The active account and hub are the source for the copy. dc-cli content-item export <dir> Export Content Items dc-cli content-item import <dir> Import content items dc-cli content-item move Move content items. The active account and hub are the source for the move. dc-cli content-item tree <dir> Print a content dependency tree from content in the given folder. dc-cli content-item unarchive [id] Unarchive Content Items Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean]
We're going to use the export command, so we'll get help for that:
dc-cli content-item export --help
The export command can be used in several ways, to export all content from a specified repository, all content in a folder, created from a given schema id, or other options including matching the name with a string.
Export Content Items Positionals: dir Output directory for the exported Content Items [string] [required] Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean] --repoId Export content from within a given repository. Directory structure will start at the specified repository. Will automatically export all contained folders. [string] --folderId Export content from within a given folder. Directory structure will start at the specified folder. Can be used in addition to repoId. [string] --facet Export content matching the given facets. Provide facets in the format 'label:example name,locale:en-GB', spaces are allowed between values. A regex can be provided for text filters, surrounded with forward slashes. For more examples, see the readme. [string] --publish When available, export the last published version of a content item rather than its newest version. [boolean] --logFile Path to a log file to write to. [string] [default: (generated-value)]
If you specify a repoId then every content item in that repository will be exported. But we want to export just the content in the "collections" folder, so we just need to specify the folderId which is unique within the hub.
To find the folder Id you can use the Dynamic Content Management API and use a tool such as Insomnia to list the folder in a repository. See the finding folder IDs section for more information.
In this example, the Id of the collections folder is 5f89ce13cff47e000168dc0f.
The list of repository folders shows that the "Collections" folder id is called "exportedCollection". Note that the client Id, secret and hub id will be read from the default configuration file, but you can also specify these credentials via the following command line.
When the command runs, the following output is shown in the command line:
Retrieving content items, please wait. Found 1 base folders. Processing ... Fetching additional folder: Collections Scanning for dependancies. Referenced content 'winter coats banner' added to the export. Referenced content 'winter dresses banner' added to the export. Referenced content 'winter hats banner' added to the export. Saving content items. exportedCollection/Summer sale carousel.json exportedCollection/Winter collection slider.json exportedCollection/Summer collection sale- carousel.json exportedCollection/Summer collection sale- dresses.json exportedCollection/Summer collection- jeans.json exportedCollection/Summer collection sale- group image.json exportedCollection/Summer collection sale- hats.json exportedCollection/Summer collection sale banner.json exportedCollection/_dependancies/winter coats banner.json exportedCollection/_dependancies/winter dresses banner.json exportedCollection/_dependancies/winter hats banner.json Log written to "/Users/yourUserName/.amplience/logs/item-export-1611927735061.log".
All of the content items in the "Collection" folder are exported, together with any content that is referenced by these items. Some of the content items are carousels, so the item they reference are exported as well, even though they're not in the "Collections" folder.
We could then choose to import these items to another hub or a different repository on the same hub.
Exporting schemas and content types and importing to another hub
When copying content between hubs, you need to ensure that the content types and schemas that used to create the content are available on the destination hub. Otherwise you wouldn't be able to work with the content on its destination hub. If you try and copy content for which a content type does not exist, then the cli-tool will display an error and the content will not be copied.
In this section we explain how to export content type schemas and content types from one hub and import them to another. You may also want to export content type schemas and content types for other reasons, such as to store them in a source control.
To export content type schemas use the export command.
dc-cli content-type-schema export --help
The options for the export command are shown in the help:
Export Content Type Schemas Positionals: dir Output directory for the exported Content Type Schema definitions [string] [required] Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean] --schemaId The Schema ID of a Content Type Schema to be exported. If no --schemaId option is given, all content type schemas for the hub are exported. A regex can be provided to select multiple type schemas with similar or matching schema ids (eg /schema(0-9)\.json/). A single --schemaId option may be given to export a single content type schema. Multiple --schemaId options may be given to export multiple content type schemas at the same time. [string] -f, --force Overwrite content type schema without asking. [boolean] --archived If present, archived content type schemas will also be considered. [boolean] --logFile Path to a log file to write to. [string] [default: (generated-value)]
By default the export command will export all unarchived schemas on a hub, but in this example we want to limit the export to those content type schemas used to create the content we want to copy: a carousel and carousel slides, and a simple banner:
The schemas will be exported to the "exportedSchemas" folder.
Note that by default archived content type schemas are excluded from the export. If you want to include archived schemas, specify the --archived option.
We also need to export the content types. Content types are registered from content type schemas and contain the settings for icons, cards and visualizations. Exporting our content types is very similar to the command we used for schemas:
To import content type schemas use the import command:
Import Content Type Schemas Positionals: dir Directory containing Content Type Schema definitions [string] [required] Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean] --logFile Path to a log file to write to. [string] [default: (generated-value)]
You'll need to specify the hubId for your destination hub or include it in your configuration file. We'll include the hubID of the "Documentation" hub:
Importing content types is very similar to the way we imported content type schemas. To import the content types from the "exportedContentTypes" folder use the following command:
You will need the content type id and the id of the repository to assign it to:
Assign Content Type Positionals: id Content Repository ID [string] [required] Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean] --contentTypeId content-type ID to assign [string] [required] --json Render output as JSON [boolean] [default: false]
The content id of the carousel is 6018318052faff00012b3bbd and we'll assign this to the "content" repository with the id of 5cf6792e4cedfd0001885b67 as follows:
To get a list of available commands related to search indexes, run command shown below in your terminal:
dc-cli search-index --help
dc-cli search-index Search Index Commands: dc-cli search-index export <dir> Export Search Indexes dc-cli search-index import <dir> Import Search Index Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean]
The search-index command category includes a number of interactions with Algolia search indexes for Dynamic Content, and can be used to export and import indexes from an individual hub.
To export search indexes from a specific Dynamic Content hub into a local folder, use the below command and specify the directory you would like the indexes to be exported to:
dc-cli search-index export <dir>
Alternatively, you can use the below command to import search indexes from a local file location into a Dynamic Content hub:
dc-cli search-index import <dir>
If you would like to import a search index without a custom payload, you would use
dc-cli search-index import ./myDirectory/indexes
Include the --webhooks command if you would like to include a custom payload.
It should be noted that using the --webhooks command will allow you to import the search-index's webhooks as well as the index itself.
This will create a file named hub-settings-5cf679244cedfd000109d2ef-ampproduct-doc.json in the "myexport" folder. The filename includes the hub id and hub name. The file includes visualization device settings, preview apps and workflow states.
These settings can then be imported into another hub.
Extensions (comprised of content field extensions, content editor extensions and dashboard extensions) can be developed using the Dynamic Content Extensions SDK, which is available in Github. In this example we're going to show how you would export all your extensions from the Dynamic Content App to a local folder.
To find the commands available for extensions, type the following in your command line:
dc-cli extension --help
dc-cli extension Extension Commands: dc-cli extension export <dir> Export Extensions dc-cli extension import <dir> Import Extensions Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean]
We're going to use the export command, so we'll get help for that:
dc-cli extension export --help
The export command can be used in several ways.
To export all extensions from specified hub you would use the hubID
To export a particular extension you would use the ID of the extension you want. If no ID is given, all extensions will be exported. You can also use multiple IDs to export multiple extensions at the same time.
To overwrite an extension without asking, you would use the --force command.
dc-cli extension export <dir> Export Extensions Positionals: dir Output directory for the exported Extensions [string] [required] Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean] --id The ID of an Extension to be exported. If no --id option is given, all extensions for the hub are exported. A single --id option may be given to export a single extension. Multiple --id options may be given to export multiple extensions at the same time. [string] -f, --force Overwrite extensions without asking. [boolean] --logFile Path to a log file to write to. [string] [default: (generated-value)]
In this example, we are exporting all extensions in our content hub to a local folder named 'exported_extensions'. To do this, we follow the below format for our command:
To import extensions from a specified filesystem location to a targeted Dynamic Content hub, you would follow a similar format to the above exporting process. First we ask for help:
dc-cli extension import --help
dc-cli extension import <dir> Import Extensions Positionals: dir Directory containing Extensions [string] [required] Options: --version Show version number [boolean] --clientId [string] [required] --clientSecret [string] [required] --hubId [string] [required] --config Path to JSON config file [string] [default: "/Users/username/.amplience/dc-cli-config.json"] --help Show help [boolean] --logFile Path to a log file to write to. [string] [default: (generated-value)]
From here on, you can import extensions from your local filesystem to your specified content hub using the following format for your command:
