Dynamic Content CLI tool
The Dynamic Content CLI tool makes it easy to access the features of the Dynamic Content Management API via the command line. Using the CLI tool you can automate common tasks such as copying content from one hub to another, importing and exporting content type schemas and content types, copying hub settings and archiving events.
On this page we'll provide an overview of the CLI tool and include some of the common use cases. Also on this page are details about setting up and configuring the tool and detailed usage examples.
Introducing the CLI toolLink copied!
With the CLI tool you can perform powerful operations in one command. In the example shown below we're copying content from a folder on one hub to a folder on another and then publishing the copied content.
dc-cli content-item copy
--srcFolder 6018216c52faff00011b2ea5 --dstFolder 5f89ce13cff47e000168dc0f --dstHubId 5cf679244cedfd000109d2ef --publish
You can can combine commands in scripts and automate a range of common tasks.
Here are some of the features that you can access from the command line using the CLI tool. For each command there are a number of options to help you configure the command to meet your requirements.
- Copy or move content between hubs or repositories on the same hub
- Import and export content items
- Revert a copy so that all the copied content is archived
- Import and export content type schemas
- Import and export content types
- Archive and unarchive content
- Import and export hub settings
- Assign and unassign content types to repositories
- Archive events
- Export and import extensions
- Clean and clone entire hubs
- Import and export search-indexes
What you can use the CLI tool forLink copied!
In this section we've included some common use cases for the CLI tool. It's not an exhaustive list and when you go through the examples and find out more about the functionality you'll probably identify more examples of how you can write some scripts to help enhance your own workflow.
Setting up a UAT or testing environmentLink copied!
If you're a developer adding new features such as previews and visualizations, or making changes to an integration, then you can use the CLI tool to copy live content into the UAT environment so you can be sure that everything works with the content that's used in a production environment.
Adding content for a new localeLink copied!
You can simplify your localization process by copying some content to the repository to which the new locale is assigned and then use these content items as the basis for your localized content.
Creating a new brandLink copied!
If you've got multiple brands within a hub you may want to copy common content from one respository to another as a quick starting point for content for the new brand.
Bulk import and export of content to and from another system- such as a translation providerLink copied!
If you're working with a translation provider you might want to export content to be translated so they can import it into a translation system. Once the content is translated you can import the content back into Dynamic Content. The CLI tool uses a mapping file to ensure that the content you import back into Dynamic Content is updated rather than new content items created.
Exporting content type schemas for storing in source controlLink copied!
You can import and export content type schemas and this is particularly useful if you want to store your schemas in a source control system. You can also make changes to schemas, re-import them and automatically sync a schema with its content type.
Moving content to reorganize itLink copied!
There are several ways you can use commands in the CLI tool to help re-organize your content. You can archive multiple content items, or copy or move selected content to a new repository to make it easier to focus on your chosen content.
Setting up and using the CLI toolLink copied!
In this section we'll show you how to install and configure it the CLI tool, and use examples to get you familiar with the main features. The CLI tool includes comprehensive online help and we show you how to use the to get more information about the parameters and options for each command.
Installing the CLI toolLink copied!
You can install the CLI tool using the Node package manager with the following command:
You can also download an executable for macOS, Windows or Unix from the releases page on GitHub.
Getting helpLink copied!
The CLI tool contains a lot of documentation built in to help you use each command. To get help type the following into the command line:
A list of the available commands and options will be displayed as follows:
To get help for a specific command, just add --help to the end of the command.
For example, to get more information about what you can do with content type schemas, enter the following in the command line:
The commands and options available for content type schemas will be displayed. You can get help for each individual command by adding --help to the end of each command.
Setting up your access IDs and keysLink copied!
API key and secret key
The CLI tool uses the Dynamic Content Management API which is authenticated using an API key and secret. You should request an API key and secret with the developer persona and with permission to read and write to the hubs that you want to use.
Hub ID
You can find the hub ID from the "Properties" menu in the Dynamic Content app, as shown in the image below. Click the icon to the right of each hub id to copy it.
Repository ID (repoId)
The id of each repository in a hub is shown in the repository window.
ConfigurationLink copied!
Each CLI tool command will require an API key and secret. This can either be specified on the command line or read from a configuration file. To set up a configuration use the configure
command:
Specify the client Id, secret and the hub you want to perform operations on from the command line:
By default the configuration file will be written to a file name "dc-cli-config.json" in a directory in your home folder, but you can specify another location in the config
option.
If you are using multiple hubs and multiple keys and secrets, you may want to create multiple configuration files. Alternatively you can specify the client Id, secret and hub Id for each command.
Additional optionsLink copied!
There are some useful options available when you copy, move or import content items from one location to another. In this section we'll explain how to use most common options.
Mapping files: updating previously copied itemsLink copied!
A mapping file is generated when you run ``dc-cli content-item copy```. This file is created in the ".amplience/imports" folder and contains the content ids of the content items on the source and destination. 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, it will look for a mapping file labelled with the source folder id. If a mapping file cannot be found, then new content items will be created in the destination.
You can specify the mapping file as an option, if you want to move it from its default location (for example if you are running a command from another device):
When you run a copy command and a map file is used, you can choose whether to update existing content items.
Here's what happens when we repeat the copy command used in the folder copy example:
Revert logs: undoing a copy or moveLink copied!
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 in 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.
We can revert the folder copy example by specifying the log file generated from the original copy:
The output generated will be as follows:
The items that were copied to the destination are now archived.
ValidateLink copied!
When running a content-item copy
, content-item move
or content-item import
you can specify the --validate
option to run the command without importing the content. You will then be able to check for any errors such as content types not existing on the destination or duplicate content items.
ForceLink copied!
The --force
option is particularly useful if you are combining multiple commands into scripts that you want to run unattended. This option will ignore any warnings and not wait for any prompts so the script can run without any user input. It is recommended that you use --validate
to identify any problems before running scripts that use the --force
option.
Cleaning an entire hubLink copied!
To explore what can be done with dc-cli hub, add --help
to the end of the dc-cli hub
command as shown below:
To clean an entire hub, you would use the dc-cli hub clean
command.
This action does not permanently all content items, types and schemas in a hub but instead archives them for future accessibility through the dc-cli import
command.
You will need to specify the destination hubID of the specific hub you would like to clean. If no hubID is given, the hub cleaned will be the same as the source hub.
If you would like to skip or step over a particular piece of content (a content item, setting, schema or type) during the cleaning process, use the --step
command and specify the content you would like to omit.
Cloning an entire hubLink copied!
To clone an entire hub from scratch, you would use the below command:
Similar to the hub clean process described above, if you would like to skip or step over a particular piece of content (a content item, setting, schema or type) during the cloning process, use the --step
command and specify the content you would like to omit from the hub clone.
In addition to this, you can also clone a hub while also including specific event circumstances, as shown in the example below:
Importing and exporting search indexesLink copied!
To get a list of available commands related to search indexes, run command shown below in your terminal:
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:
Alternatively, you can use the below command to import search indexes from a local file location into a Dynamic Content hub:
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.
Importing and exporting settingsLink copied!
You can export hub settings to a local directory using the settings command.
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.
ExamplesLink copied!
In this section we will demonstrate how to perform some common activities with the CLI tool.
Example: Exporting content itemsLink copied!
In this example we're going to show 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:
We're going to use the export command, so we'll get help for that:
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.
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. The "Content" repository has the ID 5cf6792e4cedfd0001885b67
.
From the list of folders in the repositories we can see that the id for the "Collections" folder is 5f89ce13cff47e000168dc0f
.
To export all the content in the folder to a local folder called "exportedCollection" we'll use the following command. 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 command line.
When the command runs, the following output is shown in the command line:
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.
Example: Exporting schemas and content types and importing to another hubLink copied!
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.
Exporting content type schemasLink copied!
To export content type schemas use the export command.
The options for the export command are shown in the help:
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.
Exporting content typesLink copied!
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:
The content type schemas and content types are now ready to be imported into our destination hub.
Importing content type schemasLink copied!
To import content type schemas use the import command:
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:
The content type schemas exported to the "exportedSchemas" folder have now been imported into our destination hub.
Importing content typesLink copied!
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:
The content type schemas and content types have now been imported to the destination hub and registered.
The output from the command will show each of the imported content types, together with their IDs and schema IDs.
Assigning content types to repositoriesLink copied!
There's just one more step: you need to assign each of the content types to the repositories on which you want to use them to create or edit content.
You can associate a content type with a repository using the content-repository assign-content-type
command:
dc-cli content-repository assign-content-type <id>
You will need the content type id and the id of the repository to assign it to:
The content id of the carousel is 6018318052faff00012b3bbd
and we'll assign this to the "content" repository with the id of 5cf6792e4cedfd0001885b67
as follows:
The content type is now assigned to the repository.
Example: Copying content items from one hub to anotherLink copied!
The final step is to copy the content from the "Amplience product" hub to the "Documentation" hub. You can also copy or move content from one repository to another on the same hub.
The CLI tool includes the following commands for working with content:
We want to copy the content to the destination without removing it from the source hub, so we'll use copy:
The source folder is called "Summer collection" and has an id of 6018216c52faff00011b2ea5.
This content will be copied into the "Collections" folder shown earlier that has an id of 5cf679244cedfd000109d2ef.
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.
The items have been copied to the "Collections" folder and the carousel and all its dependents have been published.
Note that currently you cannot copy between hubs on different Content Hub accounts.
Example: Exporting extensionsLink copied!
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:
We're going to use the export command, so we'll get help for that:
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.
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:
This action exports all extensions to our specified local folder.
Example: Importing extensionsLink copied!
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:
From here on, you can import extensions from your local filesystem to your specified content hub using the following format for your command: