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.

Daemon Mode

Each non-interactive CLI invocation starts the underlying Java process from scratch, which adds a short startup delay (typically a fraction of a second). For a single command this is negligible, but when a script runs dozens or hundreds of commands in sequence the overhead becomes significant.

Daemon mode eliminates this cost. The CLI process starts once, listens on a Unix domain socket, and every subsequent invocation connects to the socket and forwards its arguments instead of spawning a new process. The result is that only the first command pays the startup cost; all following commands execute at near-zero overhead.

Use daemon mode when you need to run a large number of CLI commands from a script and startup time matters.

Starting and stopping the daemon

Start the daemon explicitly in the background:

ciphermail-cli --start-daemon

Stop a running daemon:

ciphermail-cli --stop-daemon

Sending a single command to a running daemon:

ciphermail-cli --use-daemon <command>

Note

The daemon shuts itself down automatically after five minutes of inactivity (no incoming commands).

Hint

The Unix domain socket is created with 600 permissions so that only the user who started the daemon can connect to it. Other users on the same host cannot send commands to or read responses from your daemon instance.

The socket file is placed in $XDG_RUNTIME_DIR when that variable is set (typically /run/user/<uid> on systemd-based systems), or in /tmp otherwise. The file is named ciphermail-cli-<uid>.sock.

Auto-start

When the daemon socket is already present, every normal non-interactive invocation automatically routes through the daemon — no --use-daemon flag is needed:

ciphermail-cli <command>

When --use-daemon is specified and the daemon is not yet running, it is started automatically before the command is forwarded. If the daemon cannot be started in time, the command falls back to direct execution transparently.

File paths in daemon mode

When a CLI command accepts a file path (for example, a certificate or key file to import), relative paths are resolved against the directory where the daemon was started, not the directory from which the CLI command is invoked. To avoid ambiguity, use absolute paths in scripts that run under daemon mode.

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.