Introduction

You can manage the entire CipherMail Gateway from the CipherMail Command Line Interface (CLI). The CLI is especially useful for settings that are not available in the web interface and for automating installation and configuration tasks.

By using the CLI in scripts, you can reliably apply the same configuration across multiple systems, recreate test environments, and keep your changes under version control for auditing and rollback. This approach improves consistency between development, test, and production environments.

The CLI requires shell access to the server. You can connect with an SSH client, or use the built-in Terminal in the Cockpit web interface when SSH is not available. To open the Cockpit Terminal, sign in to Cockpit at https://<ip>:9090 with an administrator account and open the Terminal page (for more information acount the Cockpit App see Cockpit)

The CipherMail command-line interface (CLI) can be used in two ways: interactive and non-interactive.

In interactive mode, it runs as a Read–Eval–Print Loop (REPL): you enter a command, the CLI executes it, and the result is shown immediately before the next prompt. This mode is convenient for exploring commands, performing ad‑hoc administrative tasks, and troubleshooting because you can quickly run a series of commands in one session.

In non-interactive mode, you provide a command (and any required options) and the CLI executes it once and exits. This is ideal for scripting, automation, and scheduled tasks where you want predictable, repeatable behavior without manual input.

Use interactive mode when you want a guided, conversational workflow; use non-interactive mode when integrating the CLI into scripts or other tools.

To start a cli command in non-interactive mode:

ciphermail-cli <command>

To start the cli in interactive mode:

ciphermail-cli -i

To exit interactive mode, type exit or quit or press Control-C

Hint

By default, the CipherMail CLI client connects to the REST API at http://127.0.0.1:8081 using the cli user. You can also use the CLI client to connect to a remote server. To change the default connection settings, set the appropriate environment variables:

CIPHERMAIL_SHELL_USERNAME: The username used to authenticate with the REST API.
CIPHERMAIL_SHELL_PASSWORD: The password used to authenticate with the REST API.
CIPHERMAIL_SHELL_BASE_URL: The base URL for the REST API (for example, https://api.example.com:8443).
CIPHERMAIL_SHELL_SKIP_TLS_CHECK: When enabled, all TLS certificate and hostname verification is skipped. Use this only for testing and never in production.

Help

To get a list of all available commands, run:

ciphermail-cli help

In interactive mode use the command help

To get help for a specific CLI command, use the --help command option.

ciphermail-cli auth admin add --help

Example help output:

NAME
       auth admin add - Add new admin

SYNOPSIS
       auth admin add [--name <string>] [--authentication-type [username-password, oidc]] --help

OPTIONS
       --name <string>
       name of new admin
       [Mandatory]

       --authentication-type [username-password, oidc]
       [Mandatory]

       --help or -h
       help for auth admin add
       [Optional]

Tip

Bash tab completion is available for the ciphermail-cli command. For more comprehensive, context-aware suggestions, use interactive mode.