amplience/dc-cli

Dynamic Content CLI Tool

dc-cli

Command line interface for Amplience Dynamic Content service.

Description

dc-cli is a command line interface application for Amplience Dynamic Content management APIs.

Run dc-cli --help to get a list of available commands.

• Installation
• Configuration
  • Options
• Command categories
  • content-type-schema
  • content-type
  • content-item
  • extension
  • search-index
  • content-repository
  • event
  • settings
  • hub
• Building the CLI
• Required permissions

Installation

Installing the DC CLI from the NPM package manager can be achieved using the following command:

npm install -g @amplience/dc-cli

Or you can download the executable for your operating system on the releases page.

Configuration

dc-cli requires a valid set of Amplience client credentials (--clientId & --clientSecret) and hub ID (--hubId) to operate. These parameters must be set using the command dc-cli configure --clientId <YOUR_CLIENT_ID> --clientSecret <YOUR_CLIENT_SECRET> --hubId <YOUR_HUB_ID> before using the CLI.

Some commands (content-item copy, content-item move, & hub-clone) enable the export and import of content with a single command. These take additional options for the client credentials (--dstClientId & --dstSecret) and hub ID (--dstHubId) of a distinct Dynamic Content hub. If no destination options are provided, the destination for these commands will be the same as the source.

Once the tool has been configured the individual parameters can be overwritten by supplying them when running any of the commands, e.g dc-cli <command> <action> --hubId <YOUR_HUB_ID>.

By default the configuration is saved to a file in the directory <HOME_DIR>/.amplience/, this can be overridden using the --config option.

Options

Option Name	Type	Description
--version	[boolean]	Show version number
--clientId	[string] [required]	Client ID for the source hub
--clientSecret	[string] [required]	Client secret for the source hub
--hubId	[string] [required]	Hub ID for the source hub
--config	[string] [default: "~/.amplience/dc-cli-config.json"]	Path to JSON config file
--help	[boolean]	Show help
--logFile	[string] [default: (generated-value)]	Path to a log file to write to.
--dstHubId	[string]	Destination hub ID. If not specified, it will be the same as the source.
--dstClientId	[string]	Destination account's client ID. If not specified, it will be the same as the source.
--dstSecret	[string]	Destination account's secret. Must be used alongside dstClientId.

Examples

Create/Update configuration file for single hub

dc-cli configure --clientId foo --clientSecret bar --hubId baz

Create/Update configuration file for two-hub usage (copy/move/clone)

dc-cli configure --clientId foo --clientSecret bar --hubId baz --dstClientId qux --dstSecret quux --dstHubId quuz

Alternative Configuration using hub command

Using the hub subcommand, you can save hub configurations for retrieval later.

This command adds a hub with the supplied credentials:

dc-cli hub add --clientId <clientId> --clientSecret <clientSecret> --hubId <hubId>

Then, to use the hub, you can refer to it by name or part of the hub ID:

dc-cli hub use <hubIdOrName>

Command categories

content-type-schema

This category includes interactions with content type schemas.

These commands can be used to retrieve information on one or more schemas, create new schemas, export and import schemas from an individual hub, as well as archiving and unarchiving schemas.

View commands for content-type-schema

content-type

This category includes interactions with content types.

These commands can be used to retrieve information on one or more types, register new types or update existing ones, export and import types from an individual hub, as well as archiving and unarchiving types.

Before importing content types you must ensure that a valid content type schema exists in the destination hub for each type.

View commands for content-type

content-item

This category includes interactions with content items.

These commands can be used to export and import content from an individual hub, copy and move items between hubs, as well as archiving and unarchiving content.

Before importing, copying, or moving content you must ensure that a valid content type exists in the destination hub for each content item.

View commands for content-item

extension

This category includes interactions with Dynamic Content's UI Extensions, and can be used to export and import extensions from an individual hub.

View commands for extension

search-index

This category includes interactions with Algolia search indexes for Dynamic Content, and can be used to export and import indexes from an individual hub.

View commands for search-index

content-repository

This category includes interactions with Dynamic Content's repositories.

These commands can be used to get details for a specific repository, list multiple repositories, or assign or unassign content types from a repository.

View commands for content-repository

event

This category includes interactions with Dynamic Content's events and its constituent parts (Editions, Slots, and Snapshots). These commands can be used to export and import events, and to archive events.

View commands for event

settings

This category includes interactions with the supporting properties of a Dynamic Content hub. These commands can be used to export and import a hub's breakpoint settings for visualization, preview applications, workflow states, and locales.

View commands for settings

hub

This category includes interactions with Dynamic Content's hubs in their entirety.

These commands can be used to copy a hub's settings and content in their entirety to another hub, or to archive all parts of a hub which can be archived.

Additionally, these commands may be used to store and retrieve hub configurations.

View commands for hub

Building the CLI

We have included some NPM scripts to help create various installations of the CLI.

• Guide to building the CLI

Required permissions

Outlined below are the detailed permissions required to run each command of the CLI. To request an API key to run the CLI, please contact Amplience support.

Command	Required ACL(s)	Required Functional Permission(s)
configure	Hub - READ
content-repositories get <id>	Hub - READ	CONTENT:FUNCTIONAL:REPOSITORY:READ
content-repositories list	Hub - READ	CONTENT:FUNCTIONAL:REPOSITORY:READ
content-repositories assign-content-type <id>	ContentRepository - EDIT Hub - READ	CONTENT:FUNCTIONAL:REPOSITORY:EDIT
content-repositories unassign-content-type <id>	ContentRepository - EDIT Hub - READ	CONTENT:FUNCTIONAL:REPOSITORY:EDIT
content-type get <id>	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:READ
content-type list	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:READ
content-type register	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE
content-type sync <id>	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT
content-type update <id>	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT
content-type import <dir>	ContentRepository - EDIT Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:READ CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT
content-type export <dir>	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:READ
content-type-schema create	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE
content-type-schema get <id>	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:READ
content-type-schema list	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:READ
content-type-schema update <id>	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT
content-type-schema import <dir>	Hub - READ	CONTENT:FUNCTIONAL:CONTENT_TYPE:READ CONTENT:FUNCTIONAL:CONTENT_TYPE:CREATE CONTENT:FUNCTIONAL:CONTENT_TYPE:EDIT

dc-cli's Issues

"dc-cli content item import --publish true" fails with "Failed to initiate publish for ..."

Issue
When you import content items and set the publish flag to true, the import of items works, but then you get the error message "Failed to initiate publish for ${item.label}: ${e.toString()}" for each content item.

Steps to replicate
Run the command dc-cli content item import --publish true {credentials}

Root cause
The auth client in src/common/import/publish-queue.ts:47 requires AUTH_URL environment variable and this is not set by default.

Workaround
Set the environment variable value in your runtime environment.

Possible resolution paths
A) Initialise the auth client by using a configuration object, as happens within the ContentHub src/common/ch-api/ContentHub.ts:75.
B) Fall back to a default value in the client, as in src/common/ch-api/oauth2/services/OAuth2Client.ts:22

Include support for exporting webhooks

Currently the CLI has no commands for exporting webhooks which would be really handy right now. As there are management API calls for webhooks we could always run these ourselves, though it would be great to have this functionality as an simple CLI command.

Include export/import extensions for UI extensions

We're currently using the CLI to import/export content types, schemas and settings as a part of our deployment pipeline. The missing part for us is the import/export of UI extensions. It'd be great to get this functionality added as a part of the tool if possible.

Mapping file can get out of sync

Since the mapping file is only written to the filesystem after a complete (and successful) import run it will get out of sync when an error occurs during the import proces. Making it impossible to run the import multiple times in case of an error.

After every push to amplience the mapping file should be saved to the filesystem

Associated repos not updating

When running a Content Type export, it doesn't seem to update the associated repos list once it's been set.

I created the Content Type in the Hub with 3 repos ticked but realised later it should only have 2 ticked. Every time I run an export it returns me 3 even though it's set to 2 in the Hub.

Randomly failing tests (filesystem based tests)

Some of the tests that write & read from the file system fail.

Can we look at migrating to a mock file system instead.

Exporting Search Indexes that don't have a webhook results in an error

Exporting Search Indexes that don't have a webhook results in an error, 403 forbidden.

Improve content type syncing

Currently content type syncing requires an id but:

1. This id isn't a value that is exported (understandable from a cross-environment perspective) and although it can be retrieved from the Dynamic Content url, it would be nicer to allow it to also work with schemaId, like other parts of the cli.
2. There isn't an option to sync all content types, which would be really useful when ensuring your environment is up-to-date for example.

clean hub does not clean the entire hub

Hello,

Unfortunately the hub clean command does not get rid of everything in the Hub. Statuses are not archived and Folders are not archived / deleted too. I'd assume clean hub does archive / delete everything.

Support `--force` for export

Export operations prompt if files need to be overwritten. It would be useful if the --force parameter could be used to bypass this prompt for the sake of scripting.

validateHub doesn't respect endpoint environment vars

Should respect the AUTH_URL and API_URL overrides that other commands allow for.

Failing commands return a zero exit-code

When a command fails due to an error, we would expect this to also return a non-zero exit-code, so the error can be detected.

Currently it does not so it "seems" like the command has succeeded when it hasn't. This is misleading in automated scenarios such as CI/CD pipelines, where we would want a pipeline to report an error if a dc-cli command fails.

Schema exports can overwrite one another

Schema exports can overwrite one another when you have two schema ids with the same ending, for example:

1. https://host/segment1/test
2. https://host/segment2/test

This will export the file .../content-type-schemas/test.json for both schemas; the one that is exported last is the one that remains in the file system post-export:

{
  "body": "./schemas/test-schema.json",
  "schemaId": "https://host/segment2/test",
  "validationLevel": "CONTENT_TYPE"
}

This also applies to schema json (see "body" above) and content type exported files, where the segment is lost and exported files get overwritten.

My suggestion would be to include the segment in the path so the exported naming is more like segment1-test and segment2-test.

collisions on deliveryKey when importing a folder of content items

I keep running into collisions on deliveryKey when importing a folder of content items

running dc-cli --baseRepo 62b07a46c9e77c00010c38a5 content-item import ././wallpaperCSVs/wallpaper/MY_FOLDER_NAME --force --publish --batchPublish

The goal is that I want to upsert NEW content items using dc-cli; if item does not exist then create new, else update existing item (which is why I added --force).

I get this error almost every 2nd or 3rd attempt at running the dc-cli import command... the only "fix" I know to do it to remove the .json file that has the deliveryKey that is an issue - and attempt to reimport the folder again...

Existing mapping loaded from '/Users/robb/.amplience/imports/repo-62b07a46c9e77c00010c38a5.json', changes will be saved back to it.
Scanning structure and content in '././trbCSVs/blogs/trb-2019-schema-1680220742-clean-import' for repository 'Content'...
Done. Validating content...
Found 1 dependancy levels in 6 items, 0 referencing a circular dependancy.
Importing 6 content items...
ERROR: Failed creating Article - Ladies Turkey Hunt for Texas Rios:
Error: Request failed with status code 409: {"errors":[{"level":"ERROR","code":"CONTENT_ITEM_DELIVERY_KEY_DUPLICATE","message":"Required delivery key already exists on this hub","property":"body._meta.deliveryKey","entity":"ContentItem","invalidValue":"the-realblog-with-stephanie-mallory/ladies-turkey-hunt-for-texas-rios"}]}
Importing content item failed, aborting. Error: Error: Request failed with status code 409: {"errors":[{"level":"ERROR","code":"CONTENT_ITEM_DELIVERY_KEY_DUPLICATE","message":"Required delivery key already exists on this hub","property":"body._meta.deliveryKey","entity":"ContentItem","invalidValue":"the-realblog-with-stephanie-mallory/ladies-turkey-hunt-for-texas-rios"}]}
Log written to "/Users/robb/.amplience/logs/item-import-1680230116189.log".

Attempting to use tool for republish of a particular content type

Attempting to perform a republish for a given content type (or group of content types) for the purposes of triggering webhook background processing. The only way commands i can see to accomplish is an export and then import. But when i attempt the import with --republish, it fails due to delivery key. If i exclude keys, then a new content item is created, which is not the desired behavior.

Is this the correct process for accomplishing this task, or is there other method? May be a feature request.

Allow Import/Export/Info of Single Assets

This tool is written in a needlessly complicated way, seems unsupported, and is missing some pretty basic features, like dealing with single content-items. Would love to be proven wrong.

A massive quality-of-life improvement would be to add the ability to list content-items based solely on their folderID, "update" aka import content-items based solely on their unique UUID id, and export content-items based solely on their unique UUID id given an array of ids.

Can no longer export settings in 0.11

We were able to use settings export on 0.10 but this no longer works in 0.11, instead returning the following error:

Error: Cannot read property 'open' of undefined

This is on Windows, perhaps there has been a change to the path resolution that means this is no longer working?

Facet by deliveryKey

Hi!
It would be nice to have --facet option to check if an item has deliveryKey, so you could export and re-import items with --publish flag.
like "dc-cli content-item export [dir] --facet "deliveryKey: *"

Currently I've faced some issues while trying to clone the entire hub. Items have been correctly moved, but I couldn't publish them using cli tool.

feature request: allow import of single json file for content type (schema)

I'd like to request the ability to import a single content type / schema without importing a whole directory of json schemas.

could probably make use of loadFileFromDirectory in import.service.ts (which seems to be completely unused atm)

extend commands/content-type-schemas/import.ts handler method, check if arg in argv is dir or json filename

if arg is json filename

importedContentTypes = [new ContentTypeWithRepositoryAssignments(
  JSON.parse(
    fs.readFileSync(filename, 'utf-8')
  )
)]

or something idk

Authorization token is not refreshed

When cloning or importing hubs with +/- 14k pages the process never completes since the authorization token isn't refreshed.

Error: Request failed with status code 403: {"errors":[{"level":"ERROR","code":"FORBIDDEN","message":"Authorization required."}]}