dotCMS CLI (dotCLI) is a standalone command-line tool designed to interact with dotCMS instances. It lets developers and administrators manage configuration objects such as sites, content types, languages, templates, containers, and file assets directly from their local environments. While the dotCMS UI focuses on content management, dotCLI empowers teams to build repeatable deployments, version control their code and configurations with modern version control systems (such as Git), and automate their workflows using CI/CD pipelines.
While dotCLI is not limited to Git, this article will use Git as the version control system and GHA as the CI/CD pipeline for demonstration purposes. Multiple developers can collaborate, track changes, and ensure consistent deployments across environments by managing these objects locally and integrating with version control, making dotCLI an essential tool for modern web development.
This article will not focus on the basics of dotCLI or its commands. Instead, we will illustrate how dotCLI can be a valuable tool in CI/CD pipelines to streamline configuration management and deployment processes.
For more details about installing and using dotCLI, refer to the official documentation: dotCLI documentation. This resource provides step-by-step instructions on installing dotCLI using npm, the recommended installation method for development environments.
Configuring dotCLI to Access a dotCMS Instance
The first command to run when setting up dotCLI is config. This command allows for linking the CLI with a dotCMS instance by creating or selecting a profile. Each profile corresponds to a dotCMS instance, and the command guides you through the configuration process.
To execute the command, run:
dotcli configWhen you run the command, you might see an output similar to the following:
In this example, a new profile named demo was added, pointing to https://demo.dotcms.com.
You can activate the desired profile by running the config command again, The active profile will be used for subsequent commands. This step ensures dotCLI is correctly linked to your dotCMS instance before proceeding with workspace creation and CI/CD integration.
Similarly, you can run the instance command with the -act or --activate option to select an active target, like so:
dotcli instance -act demoThe instance command with no option will simply print a list of configured instances.
Authenticating with the dotCMS Instance
To interact with the dotCMS instance, dotCLI requires authentication. All commands communicating with the server can accept a token via the -tk or --token option. However, the recommended approach is to use the login command, which securely stores the token for the active profile.
To authenticate, run the following command:
dotcli loginThe CLI will prompt you to enter your credentials and store the token securely. This token will then be automatically injected into subsequent commands when interacting with the server. If you prefer not to store the token, you can provide it manually with each command like this:
dotcli pull --token YOUR_TOKENBy authenticating using login, you simplify interactions with the dotCMS instance and avoid repeatedly providing the token for each command. However, whereas CI/CD utilities such as GitHub Actions pass tokens as parameters on each command issued, it’s useful to be able to cover both approaches to authentication. Another useful command that can assist in correctly configuring your setup is status.
Creating a Local Workspace and Setting Up GitHub Integration
To effectively manage your dotCMS configuration, we will first create a remote GitHub repository and then initialize a local workspace linked to that repository.
Step 1: Creating and Cloning the GitHub Repository
Before setting up the dotCMS workspace, let’s create a new GitHub repository to store and version our configuration files.
For this article, we will use:
🔗 GitHub Repository: demo
Once the repository is created, clone it locally:
git clone https://github.com/fabrizzio-dotCMS/demo.gitcd demoAt this point, we have an empty repository that will soon contain our dotCMS workspace.
Step 2: Pulling dotCMS Configuration into the Workspace
Now that we have a GitHub repository prepared, we can initialize the dotCMS workspace by pulling configuration files from a dotCMS instance.
To create the workspace, run:
dotcli pullThis command retrieves the current configuration from the linked dotCMS instance and generates a workspace directory structure inside the cloned GitHub repository. After execution, the directory should look like this:
Step 3: Committing and Pushing the Workspace to GitHub
Once the workspace is set up, we need to commit the files and push them to the remote repository.
# Add all workspace files
git add .
# Commit the changes
git commit -m "Initial dotCMS workspace"
# Push the workspace to GitHub
git push origin mainStep 4: Adding GitHub Actions Workflow Configuration
To automate deployments and synchronization with dotCMS, we will now set up GitHub Actions workflows.
dotCMS provides a base workflow configuration, which can be found in the core repository:
🔗 dotCMS CLI Workflow Configuration
To integrate these workflows into our repository:
# Ensure the .github/workflows directory exists
mkdir -p .github/workflows
# Copy workflow files into the .github/workflows directory
cp /path/to/downloaded/workflows/* .github/workflows/
# Add and commit the workflow files
git add .github/workflows/*
git commit -m "Add dotCMS CLI workflow configuration"
# Push the workflow configuration to GitHub
git push origin mainNow we need to add a .env file that configures the CLI itself.
By default, the global push command does not delete files from the dotCMS instance when they are removed from GitHub. However, using the .env file, we can enable removal options.
The .env file is not created by default. It must be manually added and properly configured to avoid accidental data loss.
# Create a new .env file (if it doesn't exist)
touch .env
# Add environment variables to the .env file
echo 'DOT_CLI_OPTS=" --removeAssets --removeFolders --removeSites --removeContentTypes --removeLanguages"' >> .env
# Stage the .env file
git add .env
# Commit the changes
git commit -m "Add .env file with dotCLI options"
# Push to GitHub
git push origin mainImportant: The file is required by the workflow action, but it can be set empty if you don't want to enable these options.
Like this:
DOT_CLI_OPTS=""This configuration grants dotCLI permission to delete the following elements:
• Assets (--removeAssets)
• Folders (--removeFolders)
• Sites (--removeSites)
• Content Types (--removeContentTypes)
• Languages (--removeLanguages)
With these flags enabled, any deleted files in the GitHub repository will also be removed from the dotCMS instance upon the next push. These and other options can be configured as default behaviors in this way.
By completing this step, GitHub Actions will be able to trigger dotCLI commands automatically, enabling a fully automated CI/CD pipeline for dotCMS configuration management.
Ensuring Proper Workspace Structure
When setting up a dotCMS CLI workspace for CI/CD, it’s crucial to structure the workspace contents correctly and include all necessary files. After configuring, authenticating, and pulling the configuration, the workspace should look like this:
This structure ensures that your dotCMS configuration is properly organized, ready for version control, and capable of being deployed automatically through GitHub Actions.
Notice the .github/workflows folder and the .dot-workspace.yml and .env files
Configuring the GitHub Actions Workflow
Now that we’ve installed the GitHub Actions (GHA) configuration, the next step is to provide the necessary parameters for it to function correctly. The workflow we added requires specific environment variables and secrets to communicate with the dotCMS instance and execute CLI commands properly.
Primary Parameters (Required for Proper Workflow Execution)
1. DOT_API_URL
Description: The base URL of your dotCMS API instance. This instructs dotCLI where to send API requests. E.g.: https://demo.dotcms.com/api
2. DOT_TOKEN
Description: The API key with the necessary permissions to access and modify configurations within dotCMS. This is used to authenticate API requests.
Setting the Parameters in GitHub
For dotCLI to communicate with the dotCMS instance, these parameters must be set in the repository’s configuration. This is done through GitHub Actions settings. For a detailed explanation, please refer to the official documentation.
Enabling True CI/CD with dotCMS CLI and GitHub Actions
Now that our GitHub Actions (GHA) workflow is configured and our workspace is stored in GitHub, we can explore how this setup enables true CI/CD by automating deployments and synchronizing configurations seamlessly.
Understanding the Global Push Command
The default command executed by our workflow in GitHub Actions is global push, which synchronizes the repository’s files with the configured dotCMS instance. It’s essential to understand its behavior before making further modifications. Do not activate any of these flags unless you know the implications of removing objects from the repository.
The global push command allows us to:
• Keep dotCMS configurations in sync with a Git repository.
• Automate deployments through GitHub Actions.
• Ensure consistency across environments by version-controlling assets and configuration files.
Basic Use Case: Adding a New File
A straightforward example of how this works is adding a new file in our local repository, committing it, and pushing it to GitHub. This will trigger the global push command, automatically syncing the new file to the dotCMS instance.
Example: Adding a New Image to dotCMS
# Ensure the correct folder structure exists
mkdir -p files/live/en-us/demo.dotcms.com/images
mkdir -p files/working/en-us/demo.dotcms.com/images
# Add an image to both live and working states
cp Redline-RL20.jpg files/live/en-us/demo.dotcms.com/images/
cp Redline-RL20.jpg files/working/en-us/demo.dotcms.com/images/
# Stage the new files
git add files/live/en-us/demo.dotcms.com/images/Redline-RL20.jpg
git add files/working/en-us/demo.dotcms.com/images/Redline-RL20.jpg
# Commit and push the changes
git commit -m "Adding RL20 image"
git push origin main What Happens After the Push?
1. The GitHub Actions workflow detects the commit.
2. The workflow executes global push using dotCLI.
3. The new file is synchronized with the dotCMS instance:
• Files in files/live/ are published live.
• Files in files/working/ are staged but not published.
This demonstrates how GitHub and dotCLI allow us to decouple assets and configurations from the dotCMS UI, making them manageable via a modern version control system.
Now, let’s examine the results of this operation, starting with our GitHub repository and then reviewing the changes in our dotCMS remote instance.
Upon committing the files the new image should show in the git repository
The workflow action was triggered
Finally, this action is also reflected in the dotCMS instance
As you can see, the file was pushed into the images destination folder. It was created in status working (i.e., a draft) for the English language.
Expanding the Horizon: Future Possibilities
This is a simple example designed to highlight the immense potential of this technology. It can reshape how we work, streamlining how we modify and deploy our assets.
Imagine a scenario where developers are modifying static assets or Velocity code, managing changes through Git. By integrating Git into the workflow, we can greatly enhance how we merge updates, push changes, and deploy them efficiently.
If we need to replicate these modifications across different instances of dotCMS, the process is just as seamless. We simply adjust the configuration of our GitHub Actions (GHA) to target a new environment, and deployment can be triggered by something as simple as committing a change to a README file.
Beyond that, the GHA setup can be extended to support multiple deployment targets, providing a flexible foundation tailored to meet more complex requirements.
Taking this further, we could leverage AI to design and generate content types, feeding them directly into dotCMS. This is just one of many possibilities — there’s a vast landscape of potential use cases waiting to be explored.
Key Takeaways
1. Synchronizing Configuration via GitHub Simplifies Management
Storing dotCMS configuration files in a GitHub repository allows for better organization, version control, and automation.
By leveraging GitHub Actions (GHA), teams can automate deployments, ensuring that changes are consistently applied across environments.
2. Use GitHub Actions to Trigger dotCLI Commands Automatically
The integration between dotCLI and GitHub Actions enables a seamless CI/CD pipeline where configuration changes trigger updates in dotCMS.
The global push command ensures that the repository structure is mirrored in the dotCMS instance.
3. Be Cautious with Enabled Options
Deletion flags can permanently remove content from dotCMS.
These flags should only be enabled after careful review, as they allow dotCLI to delete assets, folders, and configurations when changes are pushed from GitHub.
4. Rollback and Restore Versions Using GitHub
Since all changes are tracked in Git, rolling back to a previous version is quick and efficient in case of accidental deletions.
This ensures that lost content can be restored without manual reconfiguration. However, if we delete a Content-type this will trigger the removal of all pieces of content that are for that type and that can not be undone.
5. dotCLI Can Be Used for More Than Just Configuration Sync
In addition to managing content types, sites, and assets, dotCLI can also push and pull specific configurations instead of the entire workspace.
This makes dotCLI a flexible tool for incremental updates.
6. GitHub Actions Enables Fully Automated Workflows
By setting up workflows, we can define when and how updates are applied to dotCMS, ensuring consistency.
Every commit to the repository can automatically sync with the dotCMS instance.
Final Thoughts
By integrating dotCLI with GitHub and GitHub Actions, organizations gain a powerful, automated, and version-controlled approach to managing dotCMS configurations. This setup improves visibility into changes with Git commits, enhances potential for collaboration, and reduces risks by allowing rollbacks and fine-grain deployment control.
With great flexibility comes great responsibility; use deletion options cautiously, validate configurations before deploying, and leverage GitHub’s versioning capabilities to maintain a stable and controlled dotCMS environment. 🚀