Setting up and using the 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.

On this page we'll introduce the CLI tool, show you how to install and configure it, 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 tool

You can install the CLI tool using the Node package manager with the following command:

npm install -g @amplience/dc-cli

You can also download an executable for macOS, Windows or Unix from the releases page on GitHub.

Getting help

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:

dc-cli --help

A list of the available commands and options will be displayed as follows:

dc-cli <command>

Commands:
  dc-cli configure            Saves the configuration options to a file
  dc-cli content-item         Content Item
  dc-cli content-repository   Content Repository
  dc-cli content-type-schema  Content Type Schema
  dc-cli content-type         Content Type
  dc-cli event                Event
  dc-cli settings             Settings

Options:
  --help          Show help                                            [boolean]
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file

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:

dc-cli content-type-schema --help

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.

Content Type Schema

Commands:
  dc-cli content-type-schema archive [id]   Archive Content Type Schemas
  dc-cli content-type-schema create         Create Content Type Schema
  dc-cli content-type-schema export <dir>   Export Content Type Schemas
  dc-cli content-type-schema get <id>       Get Content Type Schema by ID
  dc-cli content-type-schema import <dir>   Import Content Type Schemas
  dc-cli content-type-schema list           List Content Type Schemas
  dc-cli content-type-schema unarchive      Unarchive Content Type Schemas
  [id]
  dc-cli content-type-schema update <id>    Update Content Type Schema

Options:
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file

Configuration

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.

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:

dc-cli configure

Saves the configuration options to a file

Options:
  --help          Show help                                            [boolean]
  --version       Show version number                                  [boolean]
  --clientId                                                 [string] [required]
  --clientSecret                                             [string] [required]
  --hubId                                                    [string] [required]
  --config        Path to JSON config file
            [string] [default: "/Users/yourUserName/.amplience/dc-cli-config.json"]

Specify the client Id, secret and the hub you want to perform operations on from the command line:

dc-cli configure --clientId <yourClientId> --clientSecret <yourSecret> --hubId <hubId>

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.

Finding the hub ID and repository 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.

You can find the id of each hub from the properties window
You can find the id of each hub from the properties window

Similarly the id of each repository in a hub is shown in the repository window.

The id of each repository in a hub is shown in repository settings
The id of each repository in a hub is shown in repository settings

Example: Exporting content items

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.

TThe content in the collections folder we're going to export
TThe content in the collections folder we're going to export

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

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/jlansdell/.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]
  --schemaId      Export content with a given or matching Schema ID. A regex can
                  be provided, surrounded with forward slashes. Can be used in
                  combination with other filters.                       [string]
  --name          Export content with a given or matching Name. A regex can be
                  provided, surrounded with forward slashes. Can be used in
                  combination with other filters.                       [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. The "Content" repository has the ID 5cf6792e4cedfd0001885b67.

TThe content in the collections folder we're going to export
TThe content in the collections folder we're going to export

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.

dc-cli content-item export exportedCollection --folderId 5f89ce13cff47e000168dc0f

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.

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

Exporting content type schemas

To export content type schemas use the export command.

dcl-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 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]
  --archived      If present, archived content type schemas will also be
                  considered.                                          [boolean]

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:

dc-cli content-type-schema export exportedSchemas --schemaId "https://doc-example.com/carouselslide" --schemaId "https://doc-example.com/carousel" --schemaId "https://doc-example.com/simplebanner"

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 types

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:

dc-cli content-type export exportedContentTypes --schemaId "https://doc-example.com/carouselslide" --schemaId "https://doc-example.com/carousel" --schemaId "https://doc-example.com/simplebanner"

The content type schemas and content types are now ready to be imported into our destination hub.

Importing content type 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/jlansdell/.amplience/dc-cli-config.json"]
  --help          Show help                                            [boolean]

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:

dc-cli content-type-schema import exportedSchemas --hubId 5cf679244cedfd000109d2ef

The content type schemas exported to the "exportedSchemas" folder have now been imported into our destination hub.

Importing content types

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:

dc-cli content-type import exportedContentTypes --hubId 5cf679244cedfd000109d2ef

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.

+--------------------------+------------------------------------------------------------------------------------------------------+------------+
| ID                       | Schema ID                                                                                            | Result     |
|--------------------------|------------------------------------------------------------------------------------------------------|------------|
| 6018318052faff00012b3bbd | https://doc-example.com/carousel                                                                     | CREATED |
|--------------------------|------------------------------------------------------------------------------------------------------|------------|
| 601832bbc9e77c00013a809a | https://doc-example.com/carouselslide                                                                | CREATED |
|--------------------------|------------------------------------------------------------------------------------------------------|------------|
| 601825c2c9e77c00013a7e21 | https://doc-example.com/simplebanner                                                                 | CREATED |

Assigning content types to repositories

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:

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/jlansdell/.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:

dc-cli content-repository assign-content-type 5cf6792e4cedfd0001885b67 --contentTypeId 6018318052faff00012b3bbd

The content type is now assigned to the repository.

Example: Copying content items from one hub to another

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:

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 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 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/jlansdell/.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]
  --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]
  --copyConfig      Path to a JSON configuration file for source/destination
                    account. If the given file does not exist, it will be
                    generated from the arguments.                       [string]
  --lastPublish     When available, export the last published version of a
                    content item rather than its newest version.       [boolean]
  --publish         Publish any content items that have an existing publish
                    status in their JSON.                              [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]
  --logFile         Path to a log file to write to.
                                           [string] [default: (generated-value)]

The source folder is called "Summer collection" and has an id of 6018216c52faff00011b2ea5.

TThe content in the collections folder we're going to export
TThe content in the collections folder we're going to export

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:

dc-cli content-item copy --srcFolder 6018216c52faff00011b2ea5 --dstFolder 5f89ce13cff47e000168dc0f --dstHubId 5cf679244cedfd000109d2ef --publish

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: Summer collection
Scanning for dependancies.
Saving content items.
/Users/userName/.amplience/copy-1612203317991/Summer carousel.json
/Users/userName/.amplience/copy-1612203317991/Bright colours slide.json
/Users/userName/.amplience/copy-1612203317991/Sunglasses slide.json
/Users/userName/.amplience/copy-1612203317991/Hat slide.json
/Users/userName/.amplience/copy-1612203317991/Blue dress slide.json
/Users/userName/.amplience/copy-1612203317991/Get ready for summer.json
=== Importing to destination... ===
Existing mapping loaded from '/Users/userName/.amplience/imports/folder-5f89ce13cff47e000168dc0f.json', changes will be saved back to it.
Scanning structure and content in '/Users/userName/.amplience/copy-1612203317991/' for repository 'Content'...
Done. Validating content...
Found 2 dependancy levels in 6 items, 0 referencing a circular dependancy.
Importing 6 content items...
Creating circular dependants.
Resolving circular dependants.
Publishing 1 items. (4 children included)
Started publish for Summer carousel.
Waiting for all publishes to complete...
Finished publishing, with 1 failed publishes total.
 - Summer carousel
Done!

The items have been copied to the "Collections" folder and the carousel and all its dependents have been published.

The content has been copied to the collections folder on the destination hub
The content has been copied to the collections folder on the destination hub

Note that currently you cannot copy between hubs on different Content Hub accounts.

Additional options

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 items

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:

{
   "contentItems":[
      [
         "91bb8048-2553-48a2-98a3-2ea6da1f9bb5",
         "4d81e399-2415-4d50-8049-164efb7360a5"
      ],
      [
         "c397ad5b-d005-417b-865f-993c19e8a329",
         "42b7414d-f098-4c47-8b16-4ed9b6261724"
      ],
      [
         "12ba5d26-98b6-4bc4-9616-822fa5c26520",
         "656848b2-3eeb-4b51-aeae-34e1fbee8f9a"
      ],
      [
         "f84be933-fba1-4c3a-85ae-5251ab8a85a3",
         "24b46785-cc72-4003-aeb8-2a27b98bacb1"
      ],
      [
         "0c8b4c5b-4220-4425-920e-d28f5f6a2885",
         "018a826e-31d0-4677-a9a5-7e097be8db38"
      ],
      [
         "8f0a5d52-b699-474a-a9cc-2d80253e9ad8",
         "6757c1ab-6458-4ece-995e-9819a5cce7ff"
      ]
   ]
}

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

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

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:

=== Exporting from source... ===
Retrieving content items, please wait.
Found 1 base folders.
Processing ...
Fetching additional folder: Summer collection
Scanning for dependancies.
Saving content items.
/Users/userName/.amplience/copy-1612480748330/Summer carousel.json
/Users/userName/.amplience/copy-1612480748330/Bright colours slide.json
/Users/userName/.amplience/copy-1612480748330/Sunglasses slide.json
/Users/userName/.amplience/copy-1612480748330/Hat slide.json
/Users/userName/.amplience/copy-1612480748330/Blue dress slide.json
/Users/userName/.amplience/copy-1612480748330/Get ready for summer.json
=== Importing to destination... ===
Existing mapping loaded from '/Users/jlansdell/.amplience/imports/folder-5f89ce13cff47e000168dc0f.json', changes will be saved back to it.
Scanning structure and content in '/Users/jlansdell/.amplience/copy-1612480748330/' for repository 'Content'...
Done. Validating content...
6 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 6 items, 0 referencing a circular dependancy.
Importing 6 content items...
Creating circular dependants.
Resolving circular dependants.
Publishing 0 items. (0 children included)
Waiting for all publishes to complete...
Finished publishing, with 0 failed publishes total.
Done!
=== Done! ===
Log written to "/Users/userName/.amplience/logs/item-copy-1612480748330.log".

Revert logs: undoing a copy or move

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.

 --revertLog       Path to a log file to revert a copy for. This will archive
                    the most recently copied resources, and revert updated ones.

We can revert the folder copy example by specifying the log file generated from the original copy:

dc-cli content-item copy --srcFolder 6018216c52faff00011b2ea5 --dstFolder 5f89ce13cff47e000168dc0f --dstHubId 5cf679244cedfd000109d2ef --publish --config cli-config-2.json --revertLog  /Users/userName/.amplience/logs/item-copy-1612203317991.log

The output generated will be as follows:

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.

Validate

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.

Force

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.

Importing and exporting settings

You can export hub settings to a local directory using the settings command.

Commands:
  dc-cli settings export <dir>       Export Hub Settings
  dc-cli settings import <filePath>  Import Settings
dc-cli settings export /Users/yourUserName/myexport

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.

Overview of the Dynamic Content CLI tool

Dynamic Content CLI tool on GitHub