A Quickstart Guide to dotCLI (Command Line Interface)

In the world of content management systems, automation and efficient workflows are crucial for developers. The dotCMS CLI (Command Line Interface) is a powerful standalone tool that enables developers to interact with dotCMS instances through a command shell, opening up new possibilities for automation and deployment. Whether you're managing multiple environments, implementing CI/CD pipelines, or simply looking to speed up your development process, the dotCMS CLI provides the tools you need to work more efficiently.

Managing content, sites, and assets across different dotCMS environments has traditionally been a manual process through the web interface, making it time consuming and potentially error prone. Development teams often struggle with maintaining consistency across environments and integrating CMS operations into their automated deployment pipelines.

The dotCMS CLI changes this paradigm by providing a comprehensive set of commands for managing virtually every aspect of a dotCMS instance. From content types and languages to sites and file assets, the CLI offers granular control through simple command-line operations. This tool aligns with dotCMS versioning and provides native support for MacOS and Linux systems, with Windows support through WSL (Windows Subsystem for Linux).

Getting Started with dotCMS CLI

1. Installation and Configuration

The dotCMS CLI can be installed in multiple ways, with npm being the recommended method. Here's a detailed guide for different platforms:

NPM Installation (Recommended)

npm install -g @dotcms/dotcli

Platform-Specific Requirements

MacOS and Linux:

Works natively out of the box
No additional configuration needed

Windows:

Install Windows Subsystem for Linux (WSL)
Update WSL packages
Install npm within WSL

sudo apt-get update
sudo apt install npm

Note: Windows users should avoid using npm installed outside WSL to prevent installation errors.

Alternative Installation: Manual JAR Download

For cases where npm installation isn't suitable, you can download the uber-JAR directly:

Download from the CLI repository
Run using:

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

Optional: Create an alias for convenience:

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

Initial Configuration

After installation, set up your dotCMS instance:

dotcli config

This starts an interactive configuration process where you can:

Add new instances
Edit existing configurations
Set the active instance
Configure authentication credentials

2. Understanding Workspaces

A workspace is the CLI's way of organizing and managing dotCMS content locally. It serves as a mirror of your dotCMS instance, allowing you to push and pull content between your local environment and the server.

Workspace Structure

/workspace
  ├── /content-types/     # Stores content type definitions
  ├── /files/             # Contains all file assets
  ├── /languages/         # Language configurations
  ├── /sites/             # Site configurations and content
  └── .dot-workspace.yml  # Workspace configuration file

Component Details

Content Types Directory ( /content-types/ )
- Stores JSON or YAML definitions of all content types
- Each content type has its own descriptor file
- Maintains field definitions, relationships, and workflows
Files Directory ( /files/ )
- Repository for all file assets
- Follows a specific folder structure: {status}/{language}/{site}/
  - status: Can be 'live' or 'working'
  - language: Language code (e.g., 'en-us')
  - site: Site name (e.g., 'demo.dotcms.com')
- Maintains folder hierarchy from dotCMS
- Supports any file type (images, documents, etc.)
Languages Directory ( /languages/ )
- Contains language configuration files
- Stores language-specific properties
- Manages multi-language support settings
Sites Directory ( /sites/ )
- Stores JSON or YAML definitions of all sites
- Each site has its own descriptor file
- Contains site configurations including:
  - Basic info (name, identifier, aliases)
  - Status flags (live, working, archived)
  - Configuration settings
  - Site variables
Workspace Marker ( .dot-workspace.yml )
- Identifies the directory as a valid workspace
- Contains workspace-specific configurations

Creating a Workspace

A workspace can be created in two ways:

Automatic Creation

dotcli pull

This automatically generates the workspace structure when pulling from an instance.

Manual Setup
- Create the directory structure
- Add .dot-workspace.yml
- Initialize with existing content

3. Command Usage and Examples

The dotCMS CLI provides a comprehensive set of commands for managing your dotCMS instance.All commands and subcommands alike can be called with the --help (or -h) option to print additional detail. Here's an overview of the most important commands and their use cases:

Global Commands

Status and Configuration

# Check current status
dotcli status

# Configure CLI settings
dotcli config

# List available instances
dotcli instance

Authentication

# Login with username
dotcli login -u admin@dotcms.com -p

# Login with token
dotcli login -tk

Global Synchronization

# Pull everything from instance (all sites, content types, languages, and files)
dotcli pull --workspace ~/my-workspace

# Push all changes to the instance
dotcli push --retry-attempts 3

The global pull and push commands perform operations across all CLI elements:

Content Types: All content type definitions
Sites: All site configurations
Languages: All language settings
Files: All file assets

This makes them powerful tools for complete workspace synchronization, but use them carefully as they affect all components at once.

Content Type Management, Site Operations, and Language Handling

Content type, site, and language entities are handled through similar “push” and “pull”-style commands. Sites, in particular, have a larger set of commands that correspond to site creation, activity states, archival status, etc. The examples below, by no means exhaustive, highlight a few similarities and differences.

# List all available entities
dotcli content-type
dotcli site find
dotcli language find

# Pull specific item
dotcli content-type pull Blog
dotcli site pull DemoSite
dotcli language pull en-US

# Push changes
dotcli content-type push --dry-run
dotcli site push --fail-fast
dotcli language push --byIso es-ES

# Remove an item
dotcli content-type remove Blog
dotcli site remove DemoSite
dotcli language remove fr-FR

# Manage site status (unique to site commands)
dotcli site start MySite
dotcli site stop MySite
dotcli site archive MySite

File Management

The file management commands ( files tree, files ls, and files pull ) support powerful filtering options using glob patterns, giving you precise control over which files and folders to include or exclude in your operations.

# View file structure
dotcli files tree //demo.dotcms.com/application

# List directory contents with filtering
dotcli files ls //demo.dotcms.com/images \
  --excludeAsset "*.temp,*.tmp" \
  --includeFolder "public/*" \
  --excludeFolder "private/*,temp/*"

# Pull files with pattern matching
dotcli files pull \
  --includeAsset "*.pdf,*.doc" \
  --excludeAsset "draft-*" \
  --includeFolder "products/*,blog/*" \
  --excludeFolder "**/archive/**"

# Push files with watching
dotcli files push -w 5

Filtering Options:

--excludeAsset: Skip files matching these glob patterns
--excludeFolder: Skip folders matching these glob patterns
--includeAsset: Only include files matching these patterns
--includeFolder: Only include folders matching these patterns

Glob Pattern Examples:

*.pdf: Match all PDF files
draft-*: Match files starting with "draft-"
**/*.jpg: Match JPG files in any subdirectory
docs/**/2024/*: Match all files in any 2024 subdirectory under docs
**/archive/**: Match any path containing an "archive" directory

You can combine multiple patterns using commas, and mix include/exclude options for precise filtering. The patterns follow standard glob syntax, supporting wildcards ( * ), double wildcards ( ** for recursive matching ), and other glob features.

Advanced Features

Watch Mode

# Watch for file changes
dotcli push --watch 5

Safe Operations

# Dry run before actual push
dotcli push --dry-run

# Preserve existing files
dotcli files pull --preserve

Error Handling

# Enable detailed error output
dotcli status --errors

# Set retry attempts
dotcli push --retry-attempts 3 --fail-fast

Important Command Options

--dry-run: Simulate operation without making changes
--fail-fast: Stop at first error
--preserve: Keep existing files during pull
--watch: Monitor for changes
--removeAssets: Allow deletion of remote assets (archives them on the instance)
--removeFolders: Allow deletion of folders from remote instance (permanent deletion)
--forceSiteExecution: Required for site name updates

⚠️ Important Note on Removal Options:

--removeAssets safely archives assets on the remote instance
--removeFolders performs a permanent, unrecoverable deletion of folders and their contents on the remote instance
Always use --dry-run first when working with removal options to preview the changes

Remember to use dotcli <command> --help for detailed information about any command or subcommand.

Enhancing Your Development Workflow

The dotCMS CLI offers several key advantages for development teams:

Automation: Automate repetitive tasks and integrate with CI/CD pipelines
Version Control: Track changes to content types, sites, and configurations in Git
Consistency: Ensure consistency across different environments
Efficiency: Reduce manual operations and potential human errors
Integration: Seamlessly integrate with modern development workflows
Flexibility: Support for both simple operations and complex automation scenarios

When working with the dotCMS CLI, keep these important points in mind:

Safe Removal Operations: Use removal options carefully - while --removeAssets safely archives content, --removeFolders performs permanent deletion
File Naming Conventions: Be aware of filename restrictions to avoid upload failures
Token Management: Securely manage your API tokens, especially in CI/CD environments
Workspace Organization: Maintain a clear workspace structure that mirrors your production environment
Error Handling: Utilize the --retry-attempts option for robust automation scripts

Take your dotCMS development to the next level by exploring these resources:

A Quickstart Guide to dotCLI