Use the Redis command-line tool with Azure Cache for Redis

Article
09/14/2024

Use the redis-cli command-line tool to interact with an Azure Cache for Redis as a client. Use this tool to directly interact with your Azure Cache for Redis instance and for debugging and troubleshooting.

Install redis-cli

The redis-cli tool is installed automatically with the Redis package, which is available for multiple operating systems. See the open source install Redis guide for the most detailed documentation on your preferred operating system.

Linux

The redis-cli runs natively on Linux, and most distributions include a Redis package that contains the redis-cli tool. On Ubuntu, for instance, you install the Redis package with the following commands:

sudo apt-get update
sudo apt-get install redis

Windows

The best way to use redis-cli on a Windows computer is to install the Windows Subsystem for Linux (WSL). The Linux subsystem allows you to run linux tools directly on Windows. To install WSL, follow the WSL installation instructions.

Once WSL is installed, you can install redis-cli using whatever package management is available in the Linux distro you chose for WSL.

Gather cache access information

You can gather the information needed to access the cache using these methods:

Azure CLI using az redis list-keys
Azure PowerShell using Get-AzRedisCacheKey
Using the Azure portal

In this section, you retrieve the keys from the Azure portal.

Get the host name, ports, and access key

To connect to your Azure Cache for Redis server, the cache client needs the cache's host name, ports, and an access key. Some clients might refer to these items by using slightly different names. You can get the host name, ports, and keys in the Azure portal.

To get an access key for your cache:
1. In the Azure portal, go to your cache.
2. On the service menu, under Settings, select Authentication.
3. On the Authentication pane, select the Access keys tab.
4. To copy the value for an access key, select the Copy icon in the key field.
To get the host name and ports for your cache:
1. In the Azure portal, go to your cache.
2. On the service menu, select Overview.
3. Under Essentials, for Host name, select the Copy icon to copy the host name value. The host name value has the form <DNS name>.redis.cache.chinacloudapi.cn.
4. For Ports, select the Copy icon to copy the port values.

Connect using redis-cli

Open up a shell or terminal on a computer with the Redis package installed. If using WSL, you can use the Windows Terminal to open a Linux command line. Before connecting with redis-cli, check:

Whether TLS access is needed - By default, Azure Cache for Redis instances use TLS encryption for connections. Whenever TLS is used on the server side, TLS on redis-cli must be enabled using the --tls option.
The port used - Basic, Standard, and Premium tier caches, however, use either port 6379 for non-TLS connections or port 6380 for TLS connections.
Whether the cache instance uses clustering - If you're using a Premium tier cache that uses clustering, add the -coption to ensure all shards can be accessed.

Examples

Use the following command to connect to a Basic, Standard, or Premium tier Azure Cache for Redis instance using TLS:
```
redis-cli -p 6380 -h yourcachename.redis.cache.chinacloudapi.cn -a YourAccessKey --tls
```
Connect to a Basic, Standard, or Premium tier Azure Cache for Redis instance that doesn't use TLS:
```
redis-cli -p 6379 -h yourcachename.redis.cache.chinacloudapi.cn -a YourAccessKey
```
Connect to a Basic, Standard, or Premium tier Azure Cache for Redis instance using TLS and clustering:
```
redis-cli -p 6380 -h yourcachename.redis.cache.chinacloudapi.cn -a YourAccessKey --tls -c
```

Testing the connection

Once the connection is established, you can issue commands to your Azure Cache for Redis instance. One easy way to test the connection is to use the PING command. This command returns PONG in the console.

yourcachename.redis.cache.chinacloudapi.cn:6380> PING
PONG

You can also run commands like SET and GET:

yourcachename.redis.cache.chinacloudapi.cn:6380> SET hello world
OK
yourcachename.redis.cache.chinacloudapi.cn:6380> GET hello
"world"

You're now connected to your Azure Cache for Redis instance using the redis-cli.

redis-cli alternatives

While the redis-cli is a useful tool, you can connect to your cache in other ways for troubleshooting or testing:

Azure Cache for Redis offers a Redis Console built into the Azure portal where you can issue commands without needing to install the command-line tool. The Redis Console feature is currently only available in the Basic, Standard, and Premium tiers.
RedisInsight is a rich open source graphical tool for issuing Redis commands and viewing the contents of a Redis instance. It works with Azure Cache for Redis and is supported on Linux, Windows, and macOS.