Install Hermes

There are two main approaches for obtaining Hermes:

Installation:
1. If you are running on a Unix machine (Linux/macOS), then the simplest option is to download the latest binary.
2. You can also install via Cargo.
Alternatively, build Hermes directly from source.

Install by downloading

Simply head to the GitHub Releases page and download the latest version of Hermes binary matching your platform:

macOS: hermes-v1.8.0-x86_64-apple-darwin.tar.gz (or .zip),
Linux: hermes-v1.8.0-x86_64-unknown-linux-gnu.tar.gz (or .zip).

The step-by-step instruction below should carry you through the whole process:

Make the directory where we'll place the binary:
```
mkdir -p $HOME/.hermes/bin
```

Extract the binary archive:

tar -C $HOME/.hermes/bin/ -vxzf $ARCHIVE_NAME

Update your path, by adding this line in your .bashrc or .zshrc shell configuration file:
```
export PATH="$HOME/.hermes/bin:$PATH"
```

NOTE: The binary may be initially prevented from running if you're on macOS. See the "Open Anyway" instructions from this support forum if that is the case.

You should now be able to run Hermes by invoking the hermes executable.

hermes version

Which should be:

hermes v1.8.0

Install via Cargo

NOTE: This approach assumes you have installed all the prerequisites on your machine.

Hermes is packaged in the ibc-relayer-cli Rust crate. To install the latest release of Hermes, run the following command in a terminal:

cargo install ibc-relayer-cli --bin hermes --locked

This will download and build the crate ibc-relayer-cli, and install the hermes binary in $HOME/.cargo/bin.

If you have not installed Rust and Cargo via rustup.rs, you may need to add the $HOME/.cargo/bin directory to your PATH environment variable. For most shells, this can be done by adding the following line to your .bashrc or .zshrc configuration file:
export PATH="$HOME/.cargo/bin:$PATH"

You should now be able to run Hermes by invoking the hermes executable.

hermes version

Which should be:

hermes v1.8.0

Build from source

Clone the repository

Open a terminal and clone the hermes repository:

git clone https://github.com/informalsystems/hermes.git

Change to the repository directory

cd hermes

Checkout the latest release

Go to the hermes releases page to see what is the most recent release.

Then checkout the release, for example if the most recent release is v1.8.0 then execute the command:

git checkout v1.8.0

Building with `cargo build`

This command builds all the crates from the hermes repository, namely: the ibc-relayer crate, and the ibc-relayer-cli crate. The last of these crates contains the hermes binary.

cargo build --release --bin hermes

By default, Hermes bundles a telemetry service and server. To build Hermes without telemetry support, and get a smaller executable, supply the --no-default-features flag to cargo build:
cargo build --release --no-default-features --bin hermes

If the build is successful, the hermes executable will be located in the following location:

./target/release/hermes

Troubleshooting: In case the cargo build command above fails, as a first course of action we recommend trying to run the same command with the additional locked flag:

cargo build --release --bin hermes --locked

Running for the first time

If you run the hermes without any additional parameters you should see the usage and help information:

./target/release/hermes

DESCRIPTION:
Informal Systems <hello@informal.systems>
  Hermes is an IBC Relayer written in Rust

USAGE:
    hermes [OPTIONS] [SUBCOMMAND]

OPTIONS:
        --config <CONFIG>    Path to configuration file
        --debug <DEBUG>      Enable debug output for the given section(s), comma separated, can be
                             repeated. [possible values: rpc, profiling, profiling-json]
    -h, --help               Print help information
        --json               Enable JSON output
    -V, --version            Print version information

SUBCOMMANDS:
    clear           Clear objects, such as outstanding packets on a channel
    config          Generate a new Hermes configuration file or validate an existing one
    create          Create objects (client, connection, or channel) on chains
    evidence        Listen to block events and handles evidence
    fee             Interact with the fee middleware
    health-check    Performs a health check of all chains in the the config
    help            Print this message or the help of the given subcommand(s)
    keys            Manage keys in the relayer for each chain
    listen          Listen to and display IBC events emitted by a chain
    logs            Update tracing log directives
    misbehaviour    Listen to client update IBC events and handle misbehaviour
    query           Query objects from the chain
    start           Start the relayer in multi-chain mode
    tx              Create and send IBC transactions
    update          Update objects (clients) on chains
    upgrade         Upgrade objects (clients) after chain upgrade
    completions     Generate auto-complete scripts for different shells

Creating an alias for the executable

It might be easier to create an alias for hermes, so you can just run it by specifying the executable name instead of the whole path. In order to create an alias execute the following command:

alias hermes='cargo run --manifest-path $IBCFOLDER/Cargo.toml --release --bin hermes --'

The completions sub-command of Hermes can be used to output a completion script for a choice of widely used command-line shells. Refer to hermes completions --help for the list. Some shell-specific examples of setting up auto-completion with this command are provided below; check your shell configuration to decide on the suitable directory in which to install the script and any further necessary modifications to the shell's startup files.

Bash

hermes completions --shell bash
 > ~/.local/share/bash-completion/completions/hermes

On a macOS installation with Homebrew bash-completion formula installed, use

hermes completions --shell bash
 > $(brew --prefix)/etc/bash_completion.d/hermes.bash-completion

Zsh

hermes completions --shell zsh
 > ~/.zfunc/_hermes

To make the shell load the script on initialization, add the directory to fpath in your ~/.zshrc before compinit:

fpath+=~/.zfunc

Next Steps

Go to the Tutorials section to learn the basics of Hermes.

Hermes (IBC Relayer CLI) Documentation