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:
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:
| Key | Value |
|---|---|
name | The instance name as a string corresponding to a name defined in CLI configuration properties. See below for more information. |
active | The 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. |
url | Available soon. Allows definition of a URL, as a string, of the dotCMS instance. |
credentials | Authentication info as nested key-value pairs; currently accepts user and, optionally, token. |
user | Child property of credentials. Defines a username with which to access the instance, as a string. |
token | System-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/Directory | Type | Description |
|---|---|---|
/content-types/ | Dir | Stores Content Types |
/files/ | Dir | Stores file assets |
/languages/ | Dir | Stores Languages |
/sites/ | Dir | Stores Sites |
.dot-workspace.yml | File | CLI 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:
| Command | Sub-Commands | Description |
|---|---|---|
config | None | Starts an interactive configuration sequence capable of adding new instances or editing existing ones. |
status | None | Prints current active dotCMS instance, current signed-in user, and API URL. |
instance | None | Prints a list of available dotCMS instances, as defined above. |
login | None | Signs in to a dotCMS instance. |
push | None | Performs a global push, to fully synchronize a dotCMS instance with a workspace. |
pull | None | Performs a global pull, to fully synchronize a workspace with a dotCMS instance. |
content-type, ct | findpullpushremove, rm | Performs operations on Content Types. |
site, host | findpullpushcreateremove, rmcopy, cpstartstoparchiveunarchive | Performs operations on Sites. |
language, lang | findpullpushremove, rm | Performs operations on Languages. |
files | treelspullpush | 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-d], [--delete] | None | Interactive 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-act], [--activate] | Instance name | Selects 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
| Option | Parameter | Description |
|---|---|---|
-u, --user | A username | Sends a username credential for authentication. |
-p, --password | Password; if parameter is not provided, the command shell will prompt for one in a secure fashion (recommended). | Sends password for authentication. |
-tk, --token | JWT 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] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-dau], [--disable-auto-update] | None | By default, the CLI updates local file descriptors with the server response after a successful push; including this option disables that behavior. |
[--dry-run] | None | Simulates 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] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[-fse], [--forceSiteExecution] | None | Must be set to update a Site name. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[-ra], [--removeAssets] | None | When 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] | None | When 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] | None | When 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] | None | When 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] | None | When 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 Value | A 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-ff], [--fail-fast] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[-fmt], [--format] | JSONYAML, YML | Allows specification of one of two formats for pulled descriptor files. Defaults to JSON. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[--token] | Token Value | A dotCMS session token, used for authentication. |
[--workspace] | Directory Path | Specifies 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[--non-interactive] | None | When specified, all user confirmation is bypassed, allowing the command to run uninterrupted. All confirmations are active by default. |
[-n], [--name] | String | Specify a name, or partial name, by which to filter results. |
[-s], [--site] | String | Filters results by Site. |
[-o], [--order] | Property | Orders the results according to the specified property of the Content Type: variable (default), name, description, or modDate. |
[-p], [--page] | Integer | Returns a specific page of paginated results. |
[-ps], [--pageSize] | Integer | Defines 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-ff], [--fail-fast] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[-fmt], [--format] | JSONYAML, YML | Allows specification of one of two formats for pulled descriptor files. Defaults to JSON. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[--workspace] | Directory Path | Specifies 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-dau], [--disable-auto-update] | None | By default, the CLI updates local file descriptors with the server response after a successful push; including this option disables that behavior. |
[--dry-run] | None | Simulates 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] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[-rct], [--removeContentTypes] | None | When 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[--non-interactive] | None | When 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[--non-interactive] | None | When specified, all user confirmation is bypassed, allowing the command to run uninterrupted. All confirmations are active by default. |
[-ar], [--archived] | None | Show archived sites. |
[-l], [--live] | None | Show live sites. |
[-n], [--name] | String | Specify a name, or partial name, by which to filter results. |
[-p], [--page] | Integer | Returns a specific page of paginated results. |
[-s], [--pageSize] | Integer | Defines 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-ff], [--fail-fast] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[-fmt], [--format] | JSONYAML, YML | Allows specification of one of two formats for pulled descriptor files. Defaults to JSON. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[--workspace] | Directory Path | Specifies 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-dau], [--disable-auto-update] | None | By default, the CLI updates local file descriptors with the server response after a successful push; including this option disables that behavior. |
[--dry-run] | None | Simulates 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] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[-fse], [--forceSiteExecution] | None | Must be set to update a Site name. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[-rs], [--removeSites] | None | When 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[--non-interactive] | None | When 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
| Option | Parameter | Description |
|---|---|---|
-in, --idOrName | String | Specifies the Site to be copied via identifier or variable name. |
[-h], [--help] | None | Provides detailed description of command. |
[-a], [--all] | None | If specified, everything associated with the chosen Site will be copied to the new one. |
[-cn], [--copyName] | String | Supplies the name for the newly created Site. |
[-c], [--content] | None | If specified, all Site content will be copied. |
[-f], [--folder] | None | If specified, all Site folders will be copied. |
[-l], [--link] | None | If specified, all Site links will be copied. |
[-p], [--page] | None | If specified, all Site Pages and Page content will be copied. |
[-t], [--template] | None | If specified, all Site Templates will be copied. |
[-var], [--variable] | None | If 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-ff], [--fail-fast] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[-fmt], [--format] | JSONYAML, YML | Allows specification of one of two formats for pulled descriptor files. Defaults to JSON. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[--workspace] | Directory Path | Specifies 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-byIso] | ISO code | Allows 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] | None | By default, the CLI updates local file descriptors with the server response after a successful push; including this option disables that behavior. |
[--dry-run] | None | Simulates 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] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[-rl], [--removeLanguages] | None | When 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[--non-interactive] | None | When 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-d], [--depth] | Integer | Limits 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] | None | When 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] | Patterns | Excludes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-ef], [--excludeFolder] | Patterns | Excludes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-ia], [--includeAsset] | Patterns | Includes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-if], [--includeFolder] | Patterns | Includes 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-ee], [--excludeEmptyFolders] | None | When 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] | Patterns | Excludes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-ef], [--excludeFolder] | Patterns | Excludes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-ia], [--includeAsset] | Patterns | Includes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-if], [--includeFolder] | Patterns | Includes 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[-ff], [--fail-fast] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[--workspace] | Directory Path | Specifies 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] | Patterns | Excludes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-ef], [--excludeFolder] | Patterns | Excludes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-ia], [--includeAsset] | Patterns | Includes assets matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-if], [--includeFolder] | Patterns | Includes folders matching the specified glob pattern. Multiple patterns can be specified, separated by commas. |
[-ie], [--includeEmptyFolders] | None | If 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] | None | If specified, the command pulls only the specified directory and the contents within, without including subdirectories. |
[-p], [--preserve] | None | Preserves 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
| Option | Parameter | Description |
|---|---|---|
[-h], [--help] | None | Provides detailed description of command. |
[--dry-run] | None | Simulates 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] | None | Stop at the first failure, and exit the command. Without this option, default behavior is to continue after an error. |
[--retry-attempts] | Integer | Indicates a number of retry attempts on errors. Defaults to 0. |
[-ra], [--removeAssets] | None | When 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] | None | When 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 | ||
NUL | 0 | VT | 11 | SYN | 22 | ||
SOH | 1 | FF | 12 | ETB | 23 | ||
STX | 2 | CR | 13 | CAN | 24 | ||
ETX | 3 | SO | 14 | EM | 25 | ||
EOT | 4 | SI | 15 | SUB | 26 | ||
ENQ | 5 | DLE | 16 | ESC | 27 | ||
ACK | 6 | DC1 | 17 | FS | 28 | ||
BEL | 7 | DC2 | 18 | GS | 29 | ||
BS | 8 | DC3 | 19 | RS | 30 | ||
HT | 9 | DC4 | 20 | US | 31 | ||
LF | 10 | NAK | 21 |
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.”
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.
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.
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/Directory | Type | Description |
|---|---|---|
.github/workflows/ | Dir | GitHub Actions workflow |
content-types/ | Dir | Content-Types directory |
files/ | Dir | Files directory |
languages/ | Dir | Languages Directory |
sites/ | Dir | Sites Directory |
.dot-workspace.yml | File | CLI workspace marker |
.gitignore | File | Git files exclude |
README.md | File | Project readme |
.env | File | Push 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
