Installation & Configuration

Horizon Client (horizon-cli) is a single self-contained binary. This guide covers installing and configuring it on Linux and Windows.

SwissSign provides the installer for your platform during onboarding. Please contact our support if you need a new access.

Prerequisites

The installer/binary for your platform. During onboarding, SwissSign provides you with access to the download repository where you can always find the latest client version.
The endpoint URL of your Horizon instance (for example https://<your-tenant-id>.ch-1.clm.swisssign.com).
Optional: An API ID and API key for a Horizon account the client will authenticate as. These are required for authorized user authentication and all discovery operations, but not needed if you use challenge password or certificate swap (x509) mode exclusively.

Installing on Linux

Option A - RPM package (RHEL, CentOS, and compatible)

yum install horizon-cli-<version>-1.x86_64.rpm

Option B - Standalone binary (any distribution)

Apply the executable permission:
```
chmod +x horizon-cli.bin
```
Move it somewhere on your PATH (for example /usr/local/bin/horizon-cli).
Run the initial configuration step before first use.

Installing on Windows

Double-click the MSI installer and follow the wizard.

To uninstall later, open Apps & features and remove the program.

Initial configuration

The install command sets up the client and creates its configuration file:

horizon-cli install

Or pass the endpoint directly:

horizon-cli install --endpoint https://<your-horizon-instance>

If you installed from the standalone binary rather than a package or MSI, always run this first.

Configuration file location

Scope	Linux	Windows
Global	`/opt/horizon/etc/horizon-cli.conf`	`C:\ProgramData\EverTrust\Horizon\horizon-cli.conf`
Per-user	`~/.horizon-cli/etc/horizon-cli.conf`	`C:\Users\<username>\AppData\Local\horizon-cli\horizon-cli.conf`

The global file is used when the running user is an administrator and the file exists and is readable; otherwise the per-user file is used.

If the per-user file does not exist and the global file is not accessible, the client will exit with:

[FATAL] Could not load config file: EOF

Create an empty per-user configuration file to resolve this:

Linux:

mkdir -p ~/.horizon-cli/etc && touch ~/.horizon-cli/etc/horizon-cli.conf

Windows (PowerShell):

New-Item -ItemType File -Force "$env:LOCALAPPDATA\horizon-cli\horizon-cli.conf"

Configuration reference

api_id: <API ID>
api_key: <API key>
endpoint: https://<your-horizon-instance>
debug: false
timeout: 2
proxy: http://myproxy.corp.local:3128
root_ca: <Root CA PEM certificate(s)>

Parameter	Environment variable	Description
`api_id`	`HRZ_APIID`	Identifier of the Horizon account the client authenticates as.
`api_key`	`HRZ_APIKEY`	Password of the Horizon local account identified by `api_id`.
`endpoint`	`HRZ_ENDPOINT`	URL of your Horizon instance, without a trailing slash.
`debug`	`HRZ_DEBUG`	Set to `true` for verbose debug output. Defaults to `false`.
`timeout`	-	Connection timeout in seconds. Defaults to `2`.
`proxy`	`HRZ_HTTPS_PROXY`	HTTPS proxy used to reach Horizon.
`root_ca`	-	PEM chain of the CA(s) that issued Horizon's TLS certificate.
`log_file`	`HRZ_LOGFILE`	Path to the client log file.
`external_proxy`	`HRZ_EXTERNAL_PROXY`	HTTPS proxy used to reach third parties.

Verifying the installation

horizon-cli ping

To also see the permissions of the account the client is using:

horizon-cli ping --permissions

Getting help

Every command and subcommand supports --help:

horizon-cli <command> <subcommand> --help

Uninstalling

Linux (RPM): yum remove horizon-cli
Linux (binary): delete the binary from your PATH.
Windows: remove the program from Apps & features.

Installation & Configuration

On this page