Using Hydra’s CLI

The Hydra project has a command line client which can simplify working with hydra-enabled applications. In this article, we won’t cover every command — for more information see the hydra-cli documentation. Instead, we’ll look at features which are helpful to know when getting started.

Getting started

To get started you’ll need to install hydra-cli:

$ sudo npm install -g hydra-cli

You can view all of hydra-cli’s option by just typing the program name in your terminal.

As you can see there’s a lot you can do with hydra-cli.

Configuring hydra-cli

To use most hydra-cli commands you’ll need to first configure it by pointing it to the instance of Redis you’re using.

$ hydra-cli config local

The config command expects a name you’d like to associate with the Redis connection info. This allows you to store config settings for multiple environments. You might, for example, have stored settings for you projects local, staging and production environments.

Switching between stored settings is as easy as:

$ hydra-cli use staging

You can view the currently selected settings using the config list command.

$ hydra-cli config list

Working with hydra config files

Hydra config files, not to be confused with hydra-cli’s configuration settings, are used by services when they initialize hydra or hydra-express.

Those config files are commonly loaded at runtime and their contents are passed to Hydra.

During startup if Hydra see’s the HYDRA_REDIS_URL and the HYDRA_SERVICE environment variables then Hydra will ask the specified Redis instance for a copy of its config file.

This is commonly used when hydra-enabled applications are used in Docker containers.

Hydra-cli offers the cfg command for listing, loading and uploading configuration file data to Redis.

You can retrieve a list of configs using:

$ hydra-cli cfg list myservice

To store a config you’d have to specify the service name separated by a colon and the service version.

$ hydra-cli cfg pull myservice:0.12.1

Using the cfg pull command above the retrieved config would be displayed in the terminal. To save the pulled config to a file you can direct it using:

$ hydra-cli cfg pull myservice:0.12.1 > config.json

To upload a config you can use the cfg push command:

$ hydra-cli cfg push myservice:0.12.2 config.json

Listing configs, retrieving one and saving it to a file — then later modifying it prior to uploading it is how you manage your service’s configs.

Listing service info

A really nice feature of Hydra is that each application running hydra emits health and presence information. That information can be inspected by any application using hydra.

The hydra-cli program is really just a commandline client running hydra — which is what powers most of its capabilities.

We can view a list of nodes using the nodes command:

$ hydra-cli nodes

Many hydra-powered apps export API routes. We can view a list of service routes using:

$ hydra-cli routes

You can retrieve the health status of your services using the health command.

$ hydra-cli health

If you specify a service name then you’ll only see the health information for that service.

$ hydra-cli health myservice

Node list cleanup

If you start and stop services you’ll eventually see services which are no longer active. This appears during the hydra-cli nodes command. The key reason why this list isn’t automatically cleaned up is because it’s useful for debugging and monitoring reasons. You must manually clear the list of dead services using the refresh command.

$ hydra-cli refresh

Quickly connecting to Redis

If you need to, you can ask hydra-cli for a connection string for use with the redis-cli client.

$ hydra-cli shell

On machines running Mac or Linux you can issue the following command to automatically invoke redis-cli:

$(hydra-cli shell)

Next steps

Play around with hydra-cli. We’ve found it to be an indispensable tool when working with Hydra apps.