Use redis-cli to connect to an instance - Tair (Redis® OSS-Compatible)

redis-cli is the command-line tool bundled with Redis. Use it to connect to and manage ApsaraDB for Redis and Tair instances from an Elastic Compute Service (ECS) instance or an on-premises device.

Prerequisites

Before you begin, ensure that you have:

Set the password for the instance account. Use the default account password, or create a standard account with its own password. To change or reset a password, see Change or reset the password.
Added your device's IP address to the instance IP whitelist. See Set IP whitelists.
Obtained the instance endpoint. See View endpoints.

Which endpoint and IP address to use:

Device	Network	IP to whitelist	Endpoint to use
ECS instance in the same virtual private cloud (VPC) as the instance	VPC (recommended)	Private IP address of the ECS instance	VPC endpoint
ECS instance in a different VPC (for example, a different region)	Internet	Public IP address of the ECS instance	Public endpoint
On-premises device	Internet	Public IP address of the device	Public endpoint

By default, instances have only a VPC endpoint. To connect over the internet, apply for a public endpoint first.

Install redis-cli

redis-cli is installed as part of the Redis package. The redis-cli version does not need to match your instance version.

redis-cli installation instructions

Log on to the device where you want to install redis-cli, such as an ECS instance or an on-premises device.
Download and install redis-cli.
Linux
RHEL/CentOS/Alibaba Cloud Linux (yum-based):
```
# Install GCC dependencies
sudo yum -y install gcc

# Download and extract the Redis source (uses Redis 7.2.0 as an example)
wget https://download.redis.io/releases/redis-7.2.0.tar.gz
tar xzf redis-7.2.0.tar.gz

# Compile (takes 2-3 minutes)
cd redis-7.2.0 && make
```
To install a different version, see the Redis downloads page.
After compilation, redis-cli is at redis-7.2.0/src/redis-cli.
macOS
Use Homebrew to install Redis, which includes redis-cli.
Install Homebrew (if not already installed):
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Follow the on-screen instructions. You may need to enter your password.
Install Redis:
```
brew install redis
```
To find the redis-cli location after installation, run which redis-cli.
Windows
Only 64-bit Windows is supported.
1. Download Redis-x64-3.2.100.zip.
  This example uses Redis 3.2. For other versions, see MicrosoftArchive-Redis.
2. Extract the zip file to your target installation directory.

Connect to an instance

Go to the directory where redis-cli is installed.
Linux
Go to the src directory inside the Redis source folder. For example, run cd /home/redis-7.2.0/src.
macOS
Go to the Homebrew bin directory. For example, run cd /opt/homebrew/bin.
Windows
Open the command-line window and navigate to the directory where redis-cli is located.

Choose your connection command

Before running the command, confirm two things:

Your instance architecture — standard or cluster. Check the instance details page in the console.
Your connection type — VPC endpoint or public endpoint. Determines which hostname to use.

Select the command that matches your setup:

Scenario	Command
Standard architecture, or cluster architecture via proxy endpoint	`./redis-cli -h <hostname> -p <port>`
Cluster architecture via direct connection address	`./redis-cli -h <hostname> -p <port> -c`

In Windows PowerShell, replace ./redis-cli with .\redis-cli.

Parameters:

Parameter	Description	How to get it
`<hostname>`	Instance endpoint	Get the VPC endpoint or public endpoint from the console. See View endpoints.
`<port>`	Instance port	Default is `6379`. For a custom port, see Change the endpoint or port.
`-c`	Enable cluster mode	Required only for cluster architecture instances using a direct connection address.

Example:

./redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379

Authenticate
Run the AUTH command after connecting:
```
AUTH <password>
```
The password format depends on your account type:
Account type Password format Example
Default account (named default or the instance ID) Password only AUTH Rp829dlwa
Standard account user:password AUTH testaccount:Rp829dlwa
If password-free access over a VPC is enabled, skip authentication and run commands directly.

Account type	Password format	Example
Default account (named `default` or the instance ID)	Password only	`AUTH Rp829dlwa`
Standard account	`user:password`	`AUTH testaccount:Rp829dlwa`

Verify the connection

A response of OK from the AUTH command confirms you are connected. Run a quick test to verify read and write access:

set testkey "hello"    # Write a test value
OK
get testkey            # Read it back
"hello"
set tempkey "bye" EX 5 # Write with a 5-second expiration
get tempkey
"bye"
                       # Wait 5 seconds
get tempkey
(nil)                  # Key has expired

For a list of supported commands, see Command overview.

Troubleshooting

If your instance's minor version is outdated, error messages may differ from those below. Update the minor version to get the latest error messages.

Error	Cause and fix
`(error) ERR illegal address`	The connecting IP address is not in the whitelist. Add it as described in the prerequisites.
`(error) ERR client ip is not in whitelist`	Same as above.
`(error) ERR invalid password`	Incorrect password or format. For a standard account, use the `user:password` format. If you forgot the password, reset it.
`(error) WRONGPASS invalid username-password pair`	Same as above.

When using third-party tools such as RDM, enter the password in user:password format in the password field.

Tair (Redis® OSS-Compatible):Use redis-cli to connect to an instance

Prerequisites

Install redis-cli

Linux

macOS

Windows

Connect to an instance

Linux

macOS

Windows

Troubleshooting

Related topics