HCMS Command Line Interface Tool

Explains how to use the HCMS Command Line Tool to administrate HCMS configurations

Note To access all available commands and options, use --help or check this article.

Introduction

Purpose of this tool

The purpose of the HCMS command line client is to simplify administration and provide support for automation. It is intended to be used in conjunction with the HCMS Docker image. E.g., you could write an automation script that runs these CLI commands from the Terminal or other CLI.

Overview of the functionality

Indeed, the functionality is limited to administrative tasks that are HCMS-related. Using the CLI, you can manage:

• Censhare domains

• HCMS output channels

• HCMS configurations

• HCMS authentication and authorization provider configurations

The following actions can be performed:

• listing / status check

• creation

• enabling/disabling

• updates

• deletion

We recommend you to familiarize yourself with the logic behind domains and output channels before proceeding with the CLI (if you have not yet done so).

When to use CLI: a typical workflow

The CLI comes in handy for managing installations. The following workflow is highly recommended:

• create any custom domains you may need

• create all output channels you need

• create an HCMS configuration (=register your new HCMS instance) using these domains and channels

Note Alternatively, you can create a default configuration - with the root. domain and root.channel - and adjust it later.

• optionally, configure authorization providers

• optionally, configure shared file systems

• optionally, update any other configurations

Enabling, disabling, and deletion are rarely necessary.

Limitations

• Older, manually created configurations cannot be maintained using this tool

• CLI is focused on the most essential operations. Fine-tuning can be done:

  • in the Censhare Admin Client

  • by editing configuration and other related assets using Censhare Java or Web Client

Prerequisites (permission rights)

The user must have sufficient permissions to execute all necessary administration tasks (service configuration, module configuration) and to create and/or modify assets in the root. domain.
The default censhare user is the obvious choice, but any other administrator user in the root. domain can be used to run this tool.

Download and installation

HCMS CLI can be downloaded from the Download Portal. Unpack and install it like any other software.

Authentication and authorization for the CLI tool

Depending on whether you use a localhost URL or a domain URL, the authentication behaves differently, and the requirements are different:

• Passwordless authentication is to be used with the localhost URL. In the mode, the tool can be run from a local machine, but also from the Server if you cam connect to it through the ssh tunnel.

• Password authentication is required for any other server and only users with internal authorization are supported. This means that in Censhare version 2021.2 and higher, the user must be a special "system user" that is not authenticated via Keycloak.

The option with. localhost URL and SSH is even more secure than the password authentication using an internal user.

Manage HCMS server

With the HCMS server, we mean a Censhare server where the HCMS instance is registered. Consequently, "managing HCMS server" means managing the corresponding HCMS instance configuration (=HCMS service). These commands are rarely required since the configuration create command for registering the HCMS instance will also run the hcms server enable command.