Bash CLI (Legacy)

The dotCMS source code includes an example CLI written in bash to demonstrate and simplify the interaction with our REST endpoints.

It allows you to quickly bootstrap an installation and create update ContentTypes, Sites, Folders, File Assets, Containers (as files) and Templates (as files).

You can find the CLI code and an example here: https://github.com/dotCMS/core/tree/main/tools/bash-scripts

Prerequisites

Download the CLI source code

To download the code without checking out the whole dotCMS source tree, you can do something like:

git clone \
  --depth 1  \
  --filter=blob:none  \
  --sparse \
  https://github.com/dotcms/core ;
cd core
git sparse-checkout set tools/bash-scripts

This downloads the files needed to use the CLI in the directory core/tools/bash-scripts. There is an example “bundle” you can use to test with under core/tools/bash-scripts/bundles/bike-shop. The examples below are based on this bundle.

Install jq

The dotCMS CLI relies on the command line tool jq which is a commonly used CLI tool for JSON parsing.

Find a suitable version or the instructions to get it installed via package manager here.

Usage

The tool expects a directory like structure holding all the JSON descriptor/files to be pushed to dotCMS. The expected directory structure looks like this:

 /bundle
  |- /sites
      |- SYSTEM_HOST.site.json
      |- demo.dotcms.com.site.json
      / content-types
        |- blog.contenttype.json
        |- story.contenttype.json
      / files
          |- en-US 
          |   |- demo.dotcms.com (site)
          |   |  |- images (Folder)
          |   |  |  |- file1
          |   |  |  |- file2
          |   |  |- application (Folder)
          |   |     |- file3
          |   |     |- file4
          |   |
          |   |- authoring.dotcms.com
          |      |- images 
          |      |  |- file1
          |      |  |- file2
          |      |- application
          |         |- file3
          |         |- file4             
          |     
          |- es-CR 
             |- demo.dotcms.com (site)
                |- images 
                |  |- file1
                |  |- file2
                |- application
                   |- file3
                   |- file4

Usage

Config

Before you can use the tool you need to make it aware of the location of the dotCMS instance and also get a valid API Access Key associated with an authorized user. Here's how you can get a valid API Access Key, also known as a JSON Web Token. Once you have such information on hand, it must be set in the config file located in:

tools/bash-scripts/config    

The following properties are expected by the tool:

DOTCMS_BASE_URL
JSON_WEB_TOKEN
USER (Optional, in case not using JWT)
PASS (Optional, in case not using JWT)

Pushing Files and Folders

The scripts use dotCMS's the WebDAV endpoint to push files and folders. Files and folders found under each language — named according to language ISO code — will be pushed in their respective languages.

Special Json Files

Please note the file naming conventions: Content Type files must end in contenttype.json; in a similar fashion, Site definition files must end in .site.json, otherwise they will be ignored by the script.

Sites (*.site.json)

Here you can see a basic example that takes only one simple parameter Name, But you can pass much more.

Further info as to capabilities is available in our API Postman tests — specifically, Site_Resource.postman_collection.json

Content-Types (*.contenttype.json)

The Content-Type Json files used by this script are the same definitions returned by our Content-Type API

Here are a few examples:

• https://demo.dotcms.com/api/v1/contenttype/id/Product
• https://demo.dotcms.com/api/v1/contenttype/id/FileAsset
• https://demo.dotcms.com/api/v1/contenttype/id/Blog

Important: The JSON returned by those endpoints must be slightly modified to fit the requirements of our API

Many of our APIs wrap the main response body in an additional entity property. Therefore, the content type JSON body must be extracted from the entity property before putting it into a .contenttype.json file.

Another relevant detail is that Content Type definition files must be fed with a valid Site id. If not, the Content Type will be rejected.

We support pushing Content Type files using the Site na,e. Back in the server side the Site name will be resolved,
e.g.:

   "fixed":false,
   "folder":"SYSTEM_FOLDER",
   "host":"my.cool-bike.com",
   "iDate":1623251909000,
   "id":"eab1ad11292a6052b90a6247b122858b"

If your bundle has a previously created Site named my.cool-bike.com, this name can be used in your Content Type files. However, host can also be a regular valid Site identifier or name. If the host is an empty string the Content Type will be placed under System Host.

Important: When a Site name is passed to the Rest API, if the API fails to resolve the Site name, the new Content Type will be placed under System Host site as a fallback and no errors will be reported on the logs by the app.

CLI Commands

Import Bundles

Takes a folder as parameter and it can be called by doing:

./dot-cli --bundle ../bash-scripts/bundles/bike-shop  

This command takes care of loading the entire bundle into a remote instance of dotCMS.

However, if you want to do it piece by piece, there are also some other options.

Import Files

Also takes a folder as parameter and it can be called by doing:

./dot-cli --files ~/code/etc/bundle/files

This command imports the file assets section of the directory structure described above.

Import Sites

Takes a file as parameter like this:

./dot-cli --site ../bash-scripts/bundles/bike-shop/sites/my.cool-bike.com.site.json

Important: Make sure your Content Type file has valid Site identifier set when using this command, as interpolation here is of no use.

Import Content Types

Takes a file as parameter like this:

./dot-cli --content-type ../bash-scripts/bundles/bike-shop/content-types/bike.contenttype.json