dotCMS CLI

Last Updated: Apr 5, 2024
documentation for the dotCMS Content Management System

The dotCMS CLI, or dotCLI for short, is a standalone tool for interacting with a dotCMS instance through a command shell, allowing a wide array of automated operations and behaviors.

For convenience, we've also created a dotCMS CLI cheat sheet, which you can download in PDF format below:

dotCLI Cheat Sheet.

Getting Started

Installation

The simplest and most recommended way to get the dotCMS CLI is from its npm package:

npm install -g @dotcms/dotcli

After this, you can immediately begin calling dotcli commands.

Manual JAR Download

This section details an alternative, manual installation method; this is not recommended, but is presented for completeness.

As a standalone Java program, the dotCMS CLI is presented as an “uber-JAR” — a package file that also contains all relevant dependencies. In other words, you can be up and running by downloading a single file from the CLI repository. For the best results, choose the version that reflects your operating system and processor architecture.

From the appropriate directory, running it is as simple as calling the jar file with the java -jar command, e.g.:

java -jar dotcms-cli-{VERSION}.jar

For simplicity, we recommend using an alias:

alias dotcli="java -jar dotcms-cli-{VERSION}.jar"

This can be added to .bashrc, .zshrc, etc., to ensure permanence.

For information on building the dotCMS CLI from source, see the tool's GitHub readme.

Instance Configuration

To perform configuration, use dotcli config, described below.

No manual manipulation of the configuration file is necessary; all configuration is managed from within the CLI. Nevertheless, the subsection below discusses how the configuration is stored locally for informational purposes.

Configuration Storage

Configuration for the dotCMS CLI lives in a subfolder of the installation directory: /.dotcms/. Inside this folder, a dot-service.yml file is populated with block-format representations of your dotCMS instances using the following keys:

KeyValue
nameThe instance name as a string corresponding to a name defined in CLI configuration properties. See below for more information.
activeThe active instance — i.e., the one with which the CLI is currently interacting — represented by a boolean value. Only one instance can hold active: true at a time.
urlAvailable soon. Allows definition of a URL, as a string, of the dotCMS instance.
credentialsAuthentication info as nested key-value pairs; currently accepts user and, optionally, token.
userChild property of credentials. Defines a username with which to access the instance, as a string.
tokenSystem-only value. Child property of credentials. A session token saved to the YAML if and only if a native password manager is not detected, as a fallback mechanism.

The resulting file's contents might resemble this, for example:

- name: "default"
  url: "https://local.dotcms.site:8443/api"
  credentials:
    user: "admin@dotcms.com"
- name: "demo"
  active: true
  url: "https://demo.dotcms.com/api"
  credentials:
    user: "admin@dotCMS.com"

The CLI will also freely edit this file in the course of its operations — such as when, for example, when dotcli config is called, when the active instance is changed through the command line, or in the case where the system must make use of the token key.

If this file or folder is deleted, the CLI will create and populate a new one.

Workspaces

In order to interact with — namely, pushing and pulling content to and from — a dotCMS instance, the CLI uses a set of directories and files that make up a “workspace.” The workspace can be thought of as counterpart to a given instance, managed via the CLI. Workspaces can be created locally, or remotely via GitHub repo; see the section on GitHub integration for more information.

A workspace is comprised of the following directories and files:

File/DirectoryTypeDescription
/content-types/DirStores Content Types
/files/DirStores file assets
/languages/DirStores Languages
/sites/DirStores Sites
.dot-workspace.ymlFileCLI workspace marker — indicates the root directory as a valid workspace

Performing any pull operation, whether global or on an individual target, will automatically generate a workspace by creating the above file and directories, if they do not already exist.

Main Commands

The dotCMS CLI currently has ten commands that can serve as its first argument:

CommandSub-CommandsDescription
configNoneStarts an interactive configuration sequence capable of adding new instances or editing existing ones.
statusNonePrints current active dotCMS instance, current signed-in user, and API URL.
instanceNonePrints a list of available dotCMS instances, as defined above.
loginNoneSigns in to a dotCMS instance.
pushNonePerforms a global push, to fully synchronize a dotCMS instance with a workspace.
pullNonePerforms a global pull, to fully synchronize a workspace with a dotCMS instance.
content-type, ctfind
pull
push
remove, rm
Performs operations on Content Types.
site, hostfind
pull
push
create
remove, rm
copy, cp
start
stop
archive
unarchive
Performs operations on Sites.
language, langfind
pull
push
remove, rm
Performs operations on Languages.
filestree
ls
pull
push
Performs operations on file assets.

config Command

Activates an interactive command-line configuration sequence, through which instances can be edited or added.

When prompted to select a numbered item from a list, pressing Enter will exit the current phase; otherwise, pressing Enter with no input will submit the default value. On a Yes/No option, the default is whichever character is capitalized (i.e., y/N or Y/n). For string inputs — instance names or URLs — the default value will be instead displayed in square brackets.

If the --delete option is included when calling this command, the interactive menu will instead focus on the optional deletion of one or more instances.

Config Options

OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-d], [--delete]NoneInteractive menu instead allows deletion of instances.

Config Example

dotcli config
dotcli config --delete

status Command

Prints current active dotCMS instance, current signed-in user, and API URL.

Will throw a verbose error if session token has expired, suggesting the user perform the login command again.

Status Options

OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.

Status Example

dotcli status

instance Command

Prints a list of available dotCMS instances. The info includes instance names, API URL, and active status. Note that there can be only one active instance at a time; activating another instance deactivates the previous.

Instance Options

OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-act], [--activate]Instance nameSelects a new instance to serve as the active instance within the CLI.

Instance Examples

dotcli instance
dotcli instance -act demo

login Command

Establishes a token with the current active instance. Requires either the combination of --user and --password options, or the --token option, to succeed.

If using a username and password, it is recommended to omit the parameter on --password, as this will invoke the shell's password interface to prompt secure entry.

If a token is already possessed, username and password can be omitted through use of the option --token. As with --password, it is recommended to use the token option without an inline parameter, and allow the shell to prompt for it secondarily.

Login Options

OptionParameterDescription
-u, --userA usernameSends a username credential for authentication.
-p, --passwordPassword; if parameter is not provided, the command shell will prompt for one in a secure fashion (recommended).Sends password for authentication.
-tk, --tokenJWT token; similar to password, it is recommended to use this option without a parameter.Can be used instead of username or password options to authenticate a session by providing a JWT token directly.
[-h], [--help]NoneProvides detailed description of command.

Login Example

dotcli login -u admin@dotcms.com -p
dotcli login -tk

Global push [path] Command

The push command is global, fully synchronizing a target instance with a given workspace — all Sites, Content Types, Languages and Files.

As an optional argument, push takes a path to a local workspace, directory, or file; if no path argument is specified, it will default to the current working directory.

⚠️ Safe Removal Notice

Push commands are powerful — especially the global push — and care should be taken when using options that remove content from the active instance. Incautious use of removal options can delete content or directories on the active instance where the local workspace is sparsely populated.

In particular, be mindful when using --removeFolders, which performs an unrecoverable hard delete of folder contents on the target instance. Removal options for Content Types, Languages, or Sites will similarly delete items from the instance.

There is one exception: --removeAssets will merely archive the affected file assets on the active instance. However, it is worth reiterating: With all other removal options, full and irreversible deletion is always the expected behavior.

Global Push Options

OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-dau], [--disable-auto-update]NoneBy default, the CLI updates local file descriptors with the server response after a successful push; including this option disables that behavior.
[--dry-run]NoneSimulates the push operation; no changes are made to the remote server. The CLI reports what would have happened, had the push been fully conducted. This is useful for checking one's work before committing to the operation.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[-fse], [--forceSiteExecution]NoneMust be set to update a Site name.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[-ra], [--removeAssets]NoneWhen this option is enabled, the push process allows the deletion of assets from the remote server when not present in the workspace. By default, assets will not be removed on the remote server. Please see the safe removal notice for more information.
[-rct], [--removeContentTypes]NoneWhen this option is enabled, the push process allows the deletion of Content Types from the remote server when not present in the workspace. By default, Content Types will not be removed on the remote server. Please see the safe removal notice for more information.
[-rf], [--removeFolders]NoneWhen this option is enabled, the push process allows the deletion of folders from the remote server when not present in the workspace. By default, folders will not be removed on the remote server. Please see the safe removal notice for more information.
[-rl], [--removeLanguages]NoneWhen this option is enabled, the push process allows the deletion of Languages from the remote server when not present in the workspace. By default, Languages will not be removed on the remote server. Please see the safe removal notice for more information.
[-rs], [--removeSites]NoneWhen this option is enabled, the push process allows the deletion of Sites from the remote server when not present in the workspace. By default, Sites will not be removed on the remote server. Please see the safe removal notice for more information.
[--token]Token ValueA dotCMS session token, used for authentication.

Global Push Example

dotcli push ~/test-workspace --dry-run --retry-attempts 3

Global pull Command

The pull command is global, fully synchronizing a specified workspace with the active instance — all Sites, Content Types, Languages and Files. Each item is saved in a descriptor file, either JSON or YAML, named for its variable name or ISO code, in the case of Languages.

Global Pull Options

OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[-fmt], [--format]JSON
YAML, YML
Allows specification of one of two formats for pulled descriptor files. Defaults to [JSON.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[--token]Token ValueA dotCMS session token, used for authentication.
[--workspace]Directory PathSpecifies a workspace directory. Current working directory is used, if not specified. Target directory must exist prior to command, though it does not need to already be a workspace.

Global Pull Example

dotcli pull --workspace ~/test-workspace 

content-type Command

Alias: ct

Performs actions on Content Types on the active instance and/or specified workspace. Takes one of several sub-commands as an argument, listed below. If no sub-command is specified, this command will default to retrieving a full list of Content Types available on the instance.

Content Type Options

OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.

Content Type Sub-Commands

Content Type sub-commands include find, pull, push, and remove (alias rm).

content-type find Sub-Command

Returns an optionally filtered list of Content Types.

Content Type Find Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[--non-interactive]NoneWhen specified, all user confirmation is bypassed, allowing the command to run uninterrupted. All confirmations are active by default.
[-n], [--name]StringSpecify a name, or partial name, by which to filter results.
[-s], [--site]StringFilters results by Site.
[-o], [--order]PropertyOrders the results according to the specified property of the Content Type: variable (default), name, description, or modDate.
[-p], [--page]IntegerReturns a specific page of paginated results.
[-ps], [--pageSize]IntegerDefines the number of results per page returned.
content-type pull [idOrName] Sub-Command

Fetches and saves the descriptor information, as JSON or YAML, for Content Types within the instance. Each is saved in a file named after the Content Type's variable name. When a Content Type is pulled more than once, the existing descriptor file is overwritten.

Accepts an optional argument consisting of the identifier or name of the Content Type. If none is specified, this command will pull all Content Types.

Content Type Pull Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[-fmt], [--format]JSON
YAML, YML
Allows specification of one of two formats for pulled descriptor files. Defaults to JSON.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[--workspace]Directory PathSpecifies a workspace directory. Current working directory is used, if not specified. Target directory must exist prior to command, though it does not need to already be a workspace.
content-type push [path] Sub-Command

Pushes Content Types from a given workspace to the active instance.

Accepts an optional path argument to specify the source folder, or a specific Content Type descriptor file. If no path is given, the current working directory will be used.

Content Type Push Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-dau], [--disable-auto-update]NoneBy default, the CLI updates local file descriptors with the server response after a successful push; including this option disables that behavior.
[--dry-run]NoneSimulates the push operation; no changes are made to the remote server. The CLI reports what would have happened, had the push been fully conducted. This is useful for checking one's work before committing to the operation.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[-rct], [--removeContentTypes]NoneWhen this option is enabled, the push process allows the deletion of Content Types from the remote server when not present in the workspace. By default, Content Types will not be removed on the remote server. Please see the safe removal notice for more information.
content-type remove <idOrName> Sub-Command

Aliases: content-type rm

Removes a Content Type. Requires an argument consisting of the identifier or variable name of the Content Type to be removed.

Content Type Remove Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[--non-interactive]NoneWhen specified, all user confirmation is bypassed, allowing the command to run uninterrupted. All confirmations are active by default.

Content Type Examples

dotcli content-type find -n Blog
dotcli ct pull --format YAML
dotcli ct rm BlogAuthor

site Command

Alias: host

Performs actions on Sites on the active instance and/or specified workspace. Takes one of several sub-commands as an argument, listed below. If no sub-command is specified, this command will default to retrieving a full list of Sites available on the instance.

Site Options

OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.

Site Sub-Commands

Site sub-commands include find, pull, push, create, remove (or alias rm), copy (alias cp), start, stop, archive, and unarchive.

site find Sub-Command

Returns an optionally filtered list of Sites.

Site Find Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[--non-interactive]NoneWhen specified, all user confirmation is bypassed, allowing the command to run uninterrupted. All confirmations are active by default.
[-ar], [--archived]NoneShow archived sites.
[-l], [--live]NoneShow live sites.
[-n], [--name]StringSpecify a name, or partial name, by which to filter results.
[-p], [--page]IntegerReturns a specific page of paginated results.
[-s], [--pageSize]IntegerDefines the number of results per page returned.
site pull [idOrName] Sub-Command

Fetches and saves the descriptor information, as JSON or YAML, for Sites within the instance. Each is saved in a file named after the Content Type's variable name. When a Site is pulled more than once, the existing descriptor file is overwritten.

Accepts an optional argument consisting of the identifier or name of the Site. If none is specified, this command will pull all Sites.

Site Pull Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[-fmt], [--format]JSON
YAML, YML
Allows specification of one of two formats for pulled descriptor files. Defaults to JSON.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[--workspace]Directory PathSpecifies a workspace directory. Current working directory is used, if not specified. Target directory must exist prior to command, though it does not need to already be a workspace.
site push [path] Sub-Command

Pushes Sites from a given workspace to the active instance.

Accepts an optional path argument to specify the source folder, or a specific Sites descriptor file. If no path is given, the current working directory will be used.

Site Push Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-dau], [--disable-auto-update]NoneBy default, the CLI updates local file descriptors with the server response after a successful push; including this option disables that behavior.
[--dry-run]NoneSimulates the push operation; no changes are made to the remote server. The CLI reports what would have happened, had the push been fully conducted. This is useful for checking one's work before committing to the operation.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[-fse], [--forceSiteExecution]NoneMust be set to update a Site name.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[-rs], [--removeSites]NoneWhen this option is enabled, the push process allows the deletion of Sites from the remote server when not present in the workspace. By default, Sites will not be removed on the remote server. Please see the safe removal notice for more information.
site create <name> Sub-Command

Creates a new Site. Requires an argument specifying the Site's name. While a simple method to create a Site, the resulting site is completely empty of content.

For a more bells-and-whistles-included approach, consider generating a Site via site pull or site copy.

Site Create Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
site remove <idOrName> Sub-Command

Alias: site rm

Removes a Site from the active instance. Requires an argument specifying the identifier or name of the Site to be removed.

This operation is irreversible, so use it with care. Before a Site can be deleted, the Site must not be the default Site of an instance; it must be in the “stopped” state; and it must be archived.

Site Remove Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[--non-interactive]NoneWhen specified, all user confirmation is bypassed, allowing the command to run uninterrupted. All confirmations are active by default.
site copy -idOrName <idOrName> Sub-Command

Alias: site cp

This command allows the user to copy a Site and various elements belonging to it, including Pages, folders, links, Templates, Containers, and Site variables. All of these can be copied at once with --all.

This command requires the use of the --idOrName option to specify the Site to be copied. The new Site's name is specified via the --copyName option.

Site Copy Options
OptionParameterDescription
-in, --idOrNameStringSpecifies the Site to be copied via identifier or variable name.
[-h], [--help]NoneProvides detailed description of command.
[-a], [--all]NoneIf specified, everything associated with the chosen Site will be copied to the new one.
[-cn], [--copyName]StringSupplies the name for the newly created Site.
[-c], [--content]NoneIf specified, all Site content will be copied.
[-f], [--folder]NoneIf specified, all Site folders will be copied.
[-l], [--link]NoneIf specified, all Site links will be copied.
[-p], [--page]NoneIf specified, all Site Pages and Page content will be copied.
[-t], [--template]NoneIf specified, all Site Templates will be copied.
[-var], [--variable]NoneIf specified, all Site variables will be copied.
site start <idOrName> Sub-Command

Starts a Site; after a Site is created, but before it can be used, it must be Started, similar to publishing content. Requires an argument to specify the identifier or variable name of the Site to be started.

Site Start Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
site stop <idOrName> Sub-Command

Stops a Site; after a Site is stopped, it is no longer available for use, similar to unpublishing content. Requires an argument to specify the identifier or variable name of the Site to be started.

Site Stop Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
site archive <idOrName> Sub-Command

Archives a Site. Requires an argument specifying the identifier or variable name of the Site to be archived.

Similar to a stopped Site, an archived Site is not available for use; moreover it is not visible in the UI, and not available via API calls — as if it were in a Recycle Bin.

Site Archive Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
site unarchive <idOrName> Sub-Command

Unarchives a Site. Requires an argument specifying the identifier or variable name of the Site to be unarchived.

Once unarchived, a Site is once again available for use, as if retrieved from a Recycle Bin.

Site Unarchive Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.

Site Examples

dotcli site find -n Home
dotcli host cp -in Site1 -cn Site1Copy --all

language Command

Alias: lang

Performs actions on Languages on the active instance and/or specified workspace. Takes one of several sub-commands as an argument, listed below. If no sub-command is specified, this command will default to retrieving a full list of Languages available on the instances, as if calling language find.

Language Options

OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.

Language Sub-Commands

Language sub-commands include find, pull, push, and remove (alias rm).

language find Sub-Command

Returns a list of all Languages available in the system, and their respective details. No filtering is possible.

Language Find Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
language pull [languageIdOrIso] Sub-Command

Fetches and saves the descriptor information, as JSON or YAML, for Languages within the instance. Each is saved in a file named after its ISO code. When a Language is pulled more than once, the existing descriptor file is overwritten.

Accepts an optional argument consisting of the identifier or ISO code of the Language. If none is specified, this command will pull all Languages.

Language Pull Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[-fmt], [--format]JSON
YAML, YML
Allows specification of one of two formats for pulled descriptor files. Defaults to JSON.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[--workspace]Directory PathSpecifies a workspace directory. Current working directory is used, if not specified. Target directory must exist prior to command, though it does not need to already be a workspace.
language push [path] Sub-Command

Pushes Languages from a given workspace to the active instance.

Accepts an optional path argument to specify the source folder, or a specific Language descriptor file. If no path is given, the current working directory will be used.

This push command also allows, through the special --byIso option, the creation of a new Language.

Language Push Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-byIso]ISO codeAllows the creation of a new Language when one of that code is not already specified in the system. E.g.: en-us.
[-dau], [--disable-auto-update]NoneBy default, the CLI updates local file descriptors with the server response after a successful push; including this option disables that behavior.
[--dry-run]NoneSimulates the push operation; no changes are made to the remote server. The CLI reports what would have happened, had the push been fully conducted. This is useful for checking one's work before committing to the operation.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[-rl], [--removeLanguages]NoneWhen this option is enabled, the push process allows the deletion of Languages from the remote server when not present in the workspace. By default, Languages will not be removed on the remote server. Please see the safe removal notice for more information.
language remove <languageIdOrIso> Sub-Command

Alias: language rm

Removes a Language. Requires an argument consisting of the identifier or ISO code of the Language to be removed.

Language Remove Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[--non-interactive]NoneWhen specified, all user confirmation is bypassed, allowing the command to run uninterrupted. All confirmations are active by default.

Language Examples

dotcli language remove tlh-us
dotcli lang pull -h

files Command

Performs actions on file assets on the active instance and/or specified workspace. Takes one of several sub-commands as an argument, listed below. If no sub-command is specified, this command will default to the command's Help text, as if using dotcli files -h.

Files Options

OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.

Files Sub-Commands

Files sub-commands include tree, ls, pull, and push.

files tree <path> Sub-Command

This command displays a hierarchical tree view of the files and subdirectories within a specified path. Requires a path specified as an argument, in the format //{site}/{folder}.

Files Tree Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-d], [--depth]IntegerLimits the depth of the directory tree to the specified number of levels. The default value is 0, meaning only the files and directories visible from the root directory will be displayed. If --depth is called with no number specified, it will be interpreted as limitless depth.
[-ee], [--excludeEmptyFolders]NoneWhen specified, the tree display will exclude folders that do not contain any assets, as well as folders that have no children with assets, making the output more concise and easy to navigate. By default, all folders, will be displayed in the tree.
[-ea], [--excludeAsset]PatternsExcludes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-ef], [--excludeFolder]PatternsExcludes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-ia], [--includeAsset]PatternsIncludes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-if], [--includeFolder]PatternsIncludes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
files ls <path> Sub-Command

This command lists the files and directories in the specified directory. It requires an argument in the form of a directory path.

Files LS Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-ee], [--excludeEmptyFolders]NoneWhen specified, the tree display will exclude folders that do not contain any assets, as well as folders that have no children with assets, making the output more concise and easy to navigate. By default, all folders, will be displayed in the tree.
[-ea], [--excludeAsset]PatternsExcludes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-ef], [--excludeFolder]PatternsExcludes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-ia], [--includeAsset]PatternsIncludes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-if], [--includeFolder]PatternsIncludes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
files pull Sub-Command

This command pulls files from the dotCMS instance to the indicated workspace.

Accepts an optional argument consisting a path to either a Site, folder, or individual file. If no path is specified, this command will pull all file assets from all Sites within a dotCMS instance. This path argument should be formatted //{site}/{folder}/{file}.

Files Pull Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[--workspace]Directory PathSpecifies a workspace directory. Current working directory is used, if not specified. Target directory must exist prior to command, though it does not need to already be a workspace.
[-ea], [--excludeAsset]PatternsExcludes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-ef], [--excludeFolder]PatternsExcludes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-ia], [--includeAsset]PatternsIncludes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-if], [--includeFolder]PatternsIncludes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas.
[-ie], [--includeEmptyFolders]NoneIf specified, the pull process will create empty folders in the workspace where they exist on the active instance. By default, empty folders are not created.
[-nr], [--nonRecursive]NoneIf specified, the command pulls only the specified directory and the contents within, without including subdirectories.
[-p], [--preserve]NonePreserves existing files and directories, avoiding overwriting them if they already exist.
files push Sub-Command

Pushes files from a given workspace to the active instance.

Accepts an optional path argument to specify a site, folder, or a specific file. If no path is given, the current working directory will be used.

Files Push Options
OptionParameterDescription
[-h], [--help]NoneProvides detailed description of command.
[--dry-run]NoneSimulates the push operation; no changes are made to the remote server. The CLI reports what would have happened, had the push been fully conducted. This is useful for checking one's work before committing to the operation.
[-ff], [--fail-fast]NoneStop at the first failure, and exit the command. Without this option, default behavior is to continue after an error.
[--retry-attempts]IntegerIndicates a number of retry attempts on errors. Defaults to 0.
[-ra], [--removeAssets]NoneWhen this option is enabled, the push process allows the deletion of file assets from the remote server when not present in the workspace. By default, files will not be removed on the remote server. Please see the safe removal notice for more information.
[-rf], [--removeFolders]NoneWhen this option is enabled, the push process allows the deletion of folders from the remote server when not present in the workspace. By default, folders will not be removed on the remote server. Please see the safe removal notice for more information.

Files Examples

dotcli files pull --excludeAsset Rumpel*kin -p
dotcli files tree //demo.dotcms.com/application

Global Options

The following options are available at all times within the CLI, regardless of command or subcommand.

Help

Flags: -h, --help

The universally available Help option provides a detailed explanation of a given command or subcommand. Examples:

dotcli login --help
dotcli site find -h 

This has been included in the options tables for each command and subcommand for quick reference.

Token

Flags: -tk, --token

Takes a JWT token. Though specified under the login command, strictly speaking the Token option can be applied to any CLI call to use an individual command without committing to session-wide authentication.

dotcli pull -tk $TOK

Version

Flags: -V, --version

With a Version flag in place, the CLI will simply print its current version information and exit. Example:

dotcli -V

Error

Flags: -e, --errors

When a command invokes the Error option, it will return a stack trace detailing any error it encounters during execution. Example:

dotcli status -e

File Name Limits

There are certain characters dotCMS does not permit as part of a file name, mainly for security reasons. When uploading a file via the user interface, these special characters are replaced automatically in the background. However, due to architectural considerations — especially the potential for conflicts in a CI/CD environment with any number of local filenames differing from their remote counterparts — we have ruled it safer for the CLI to simply fail an upload with an illegal filename.

The list of illegal characters consists mostly of control codes, but does also include more straightforwardly typable characters. Below is a table containing the full list of filename characters that will be rejected when pushed from a dotCLI Workspace.

Illegal
Char.
ASCII
Code
Illegal
Char.
ASCII
Code
Illegal
Char.
ASCII
Code
"34*42/47
:58<60>62
?63\92|124
NUL0VT11SYN22
SOH1FF12ETB23
STX2CR13CAN24
ETX3SO14EM25
EOT4SI15SUB26
ENQ5DLE16ESC27
ACK6DC117FS28
BEL7DC218GS29
BS8DC319RS30
HT9DC420US31
LF10NAK21

GitHub Integration

The dotCMS CLI can use a GitHub repository as a workspace, allowing you to incorporate powerful GitHub Actions into your CI/CD pipeline.

To get up and running, start by creating a GitHub repository.

From the dotCMS CLI repository, copy the contents of the /action/ directory into your repo's root. It will appear as a populated .github/workflows/ directory.

Browse to your repository's Settings, then to Actions -> General. Near the bottom of the page, ensure Workflow Permissions are set to “Read and Write permissions.”

GitHub variables menu.

Next, browse within Settings to Secrets and Variables -> Actions. Create a new variable called DOT_API_URL and set the value to a valid dotCMS URL — e.g., https://demo.dotcms.com/api.

GitHub secrets menu.

Finally, create a new secret in the other tab of Action Secrets and Variables, and name it DOT_TOKEN. Its value must be a valid dotCMS CLI token. To obtain a dotCMS token, browse the dotCMS admin panel to Settings -> Users -> API Access Tokens, and generate a token. Store that token in the DOT_TOKEN secret you created in the GitHub Actions secrets.

Getting a dotCMS API token.

Quickly create a workspace in your repository by calling dotcli pull on your dotCMS instance, then commit and push the changes to your repository.

If the integration has been successful, you should see a new commits made into your repository are quickly reflected in your dotCMS instance.

Here's an example of how a Git repository might look after the GitHub Action has been integrated:

File/DirectoryTypeDescription
.github/workflows/DirGitHub Actions workflow
content-types/DirContent-Types directory
files/DirFiles directory
languages/DirLanguages Directory
sites/DirSites Directory
.dot-workspace.ymlFileCLI workspace marker
.gitignoreFileGit files exclude
README.mdFileProject readme
.envFilePush command Options Spec

The default command executed by our GitHub Action is the (global) push. Any options desired for this command can be specified in the .env file in the following format:

DOT_CLI_OPTS="--option1 --option2 ..." 

A valid option assignment might resemble the following example:

DOT_CLI_OPTS="--forceSiteExecution --dry-run --retry-attempts 3"

Log File

All operations performed by the dotCMS CLI appear in a log file: dotcms-cli.log.

By default, this file appears in the installation directory. However, this target location can be overridden via environment variable.

For example:

export QUARKUS_LOG_FILE_PATH=~/.dotcms/log/dotcms-cli.log

Alternately, you can define that variable in a .env file in the same directory:

# dotCMS CLI log redirect
QUARKUS_LOG_FILE_PATH=~/.dotcms/log/dotcms-cli.log

On this page

×

We Dig Feedback

Selected excerpt:

×