Use redis-cli to connect to an ApsaraDB for Redis instance - User Guide| Alibaba Cloud Documentation Center

redis-cli is a built-in command line interface (CLI) of Redis. You can use redis-cli to connect to an ApsaraDB for Redis instance from an Elastic Compute Service (ECS) instance or on-premises device to manage data.

redis-cli is automatically installed when you install Redis on your ECS instance or on-premises device. For more information about ECS, see What is ECS? If you use redis-cli to connect to an ApsaraDB for Redis instance, redis-cli does not need to have the same version as the ApsaraDB for Redis instance.

Note You can also connect to databases in an ApsaraDB for Redis instance by using Data Management (DMS). For more information about DMS, see Overview. This method does not require a client and allows you to visually manage databases. For more information about this method, see Log on to an ApsaraDB for Redis instance by using DMS.

Workflow


Procedure	Description
1. Specify the account used to connect to an ApsaraDB for Redis instance and the account password.	The following methods are available: Specify the password for the default account of the ApsaraDB for Redis instance. For more information, see Change or reset the password. Specify a custom account and its password. For more information, see Create and manage database accounts.
2. Configure a whitelist.	The recommended network type varies with device. ECS instance (recommended): VPC is recommended. Make sure that the ECS instance and the ApsaraDB for Redis instance are deployed in the same VPC and that a whitelist of the ApsaraDB for Redis instance contains the private IP address of the ECS instance. Note If the ECS instance and the ApsaraDB for Redis instance are deployed in different VPCs, add the public IP address of the ECS instance to a whitelist of the ApsaraDB for Redis instance and connect to the ApsaraDB for Redis instance over the Internet. On-premises device: Internet can be used. Add the public IP address of the on-premises device to a whitelist of the ApsaraDB for Redis instance. For more information, see Configure whitelists.
3. Obtain the connection information.	If you use a VPC, obtain the endpoint of the ApsaraDB for Redis instance in the VPC in the ApsaraDB for Redis console. If you use the Internet, apply for a public endpoint for the ApsaraDB for Redis instance and obtain the allocated public endpoint in the ApsaraDB for Redis console. For more information, see Apply for a public endpoint for an ApsaraDB for Redis instance. Note By default, only VPC endpoints are available for ApsaraDB for Redis instances. If you want to connect to an ApsaraDB for Redis instance over the Internet, you must apply for a public endpoint. For more information, see View endpoints.
4. Use redis-cli to connect to the ApsaraDB for Redis instance.	Run the following commands based on your needs in the decompressed redis-cli directory: Command syntax used to establish a connection: `redis-cli -h hostname -p port` Sample command: `redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379` Command syntax used to enter a password: `AUTH user:password` Sample command: `AUTH testaccount:Rp829dlwa` For more information, see the Procedure section of this topic.

Procedure

Linux

Install redis-cli. Skip this step if it is already installed.
1. Log on to the device on which you want to install redis-cli, such as an ECS instance or an on-premises device.
2. Run the following command to download the Redis source code package:
```
wget https://download.redis.io/releases/redis-6.0.9.tar.gz
```
  Note Redis 6.0.9 is used in this example to demonstrate the operations. You can install other versions. For more information, visit Download.
3. Run the following command to decompress the Redis source code package:
```
tar xzf redis-6.0.9.tar.gz
```
4. Run the following command to go to the directory to which the Redis source code package is decompressed. Then, compile and install Redis.
```
cd redis-6.0.9&&make
```
  Note It takes 2 or 3 minutes to compile and install Redis.

Obtain the connection information and run the following command to connect to the ApsaraDB for Redis instance:

src/redis-cli -h hostname -p port [-c]

Table 1. Parameters
Parameter	Description	Method to obtain the parameter value
hostname	The endpoint of the ApsaraDB for Redis instance.	If you connect to the ApsaraDB for Redis instance over a VPC, obtain the endpoint of the ApsaraDB for Redis instance in the VPC. If you connect to the ApsaraDB for Redis instance over the Internet, obtain the public endpoint of the ApsaraDB for Redis instance. For more information, see View endpoints.
port	The port number of the ApsaraDB for Redis instance.	Use the default port number 6379 or specify a custom port number. For more information, see Change the endpoint or port number of an ApsaraDB for Redis instance.
-c	Enables the cluster mode.	The cluster mode is available only if the ApsaraDB for Redis instance is a cluster instance that uses a private endpoint. For more information, see Cluster master-replica instances and Enable the direct connection mode.

Connection examples:

The following sample command is suitable for scenarios where ApsaraDB for Redis instances are connected by using default endpoints, such as endpoints of standard instances and proxy endpoints of cluster instances:
```
src/redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379
```
The following sample command is suitable for scenarios where ApsaraDB for Redis cluster instances are connected by using private endpoints:
```
src/redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379 -c
```

Run the following command to verify the password:

AUTH password

Table 2. Parameters
Parameter	Description
password	The password of the account. If you use the default account whose username is the same as the instance ID, enter the password. If you use a custom account, enter the password in the `user:password` format. For example, if the username of the custom account is `testaccount` and the password is `Rp829dlwa`, enter `testaccount:Rp829dlwa` as the password. Note If you forget the password or have not set a password, you can reset the password. For more information, see Change or reset the password. If password-free access is enabled for the ApsaraDB for Redis instance, you can run Redis commands without performing this step when you connect to the instance over a VPC. For more information, see Enable password-free access.

Sample command:

AUTH testaccount:Rp829dlwa

If OK is displayed, the ApsaraDB for Redis instance is connected and Redis commands can be run on the instance.

For more information about what to do if an error occurs, see Common connection errors.
For more information about the commands supported by ApsaraDB for Redis, see Overview.

Windows

Only 64-bit Windows operating systems are supported.

Install redis-cli. Skip this step if it is already installed.
1. Log on to the device on which you want to install redis-cli, such as an ECS instance or an on-premises device.
2. Download the Redis-x64-3.2.100.zip package.
  
  Note Redis on Windows 3.2 is used in this example to demonstrate the operations. You can also install other versions. For more information, visit MicrosoftArchive-Redis.
3. Decompress the Redis-x64-3.2.100.zip package to the directory where you want to install Redis. The D:\Redis-x64-3.2.100 directory is used in this example.
On the ECS instance or on-premises device where redis-cli is installed, press Win+R to open the Run dialog box. In the Run dialog box, enter cmd and click OK.
The Windows CLI is opened.

Figure 1. Windows CLI
Run the following command to access the directory where redis-cli is installed:
In this example, D:\Redis-x64-3.2.100 is the full path of the directory to which the Redis-x64-3.2.100.zip package is decompressed. Sample command:
```
cd /d D:\Redis-x64-3.2.100
```

Obtain the connection information and run the following command to connect to the ApsaraDB for Redis instance:

redis-cli -h hostname -p port [-c]

Note If you want to start redis-cli in PowerShell, run the .\redis-cli -h hostname -p port [-c] command.

Table 3. Parameters
Parameter	Description	Method to obtain the parameter value
hostname	The endpoint of the ApsaraDB for Redis instance.	If you connect to the ApsaraDB for Redis instance over a VPC, obtain the endpoint of the ApsaraDB for Redis instance in the VPC. If you connect to the ApsaraDB for Redis instance over the Internet, obtain the public endpoint of the ApsaraDB for Redis instance. For more information, see View endpoints.
port	The port number of the ApsaraDB for Redis instance.	Use the default port number 6379 or specify a custom port number. For more information, see Change the endpoint or port number of an ApsaraDB for Redis instance.
-c	Enables the cluster mode.	The cluster mode is available only if the ApsaraDB for Redis instance is a cluster instance that uses a private endpoint. For more information, see Cluster master-replica instances and Enable the direct connection mode.

Connection examples:

The following sample command is suitable for scenarios where ApsaraDB for Redis instances are connected by using default endpoints, such as endpoints of standard instances and proxy endpoints of cluster instances:
```
redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379
```
The following sample command is suitable for scenarios where ApsaraDB for Redis cluster instances are connected by using private endpoints:
```
redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379 -c
```

Run the following command to verify the password:

AUTH password

Table 4. Parameters
Parameter	Description
password	The password of the account. If you use the default account whose username is the same as the instance ID, enter the password. If you use a custom account, enter the password in the `user:password` format. For example, if the username of the custom account is `testaccount` and the password is `Rp829dlwa`, enter `testaccount:Rp829dlwa` as the password. Note If you forget the password or have not set a password, you can reset the password. For more information, see Change or reset the password. If password-free access is enabled for the ApsaraDB for Redis instance, you can run Redis commands without performing this step when you connect to the instance over a VPC. For more information, see Enable password-free access.

Sample command:

AUTH testaccount:Rp829dlwa

If OK is displayed, the ApsaraDB for Redis instance is connected and Redis commands can be run on the instance.

For more information about what to do if an error occurs, see Common connection errors.
For more information about the commands supported by ApsaraDB for Redis, see Overview.

Common connection errors

Note If the minor version of your instance is outdated, the returned error messages may be inconsistent with those listed in the following table. We recommend that you update your instance to the latest minor version. For more information, see Update the minor version.


Error message	Cause and solution
`(error) ERR illegal address`	A whitelist is not configured as required. For more information, see the Workflow section of this topic.
`(error) ERR client ip is not in whitelist`
`(error) ERR invalid password` `(error) WRONGPASS invalid username-password pair`	The password is invalid. Specify the correct password in a valid format. The password format varies with the account type. If you use the default account whose username is the same as the instance ID, enter the password. If you use a custom account, enter the password in the `user:password` format. For example, if the username of the custom account is `testaccount` and the password is `Rp829dlwa`, enter `testaccount:Rp829dlwa` as the password. Note If you use a third-party database management tool such as Remote Desktop Manager (RDM) to connect to an ApsaraDB for Redis instance, enter the password in the `user:password` format. If you forget your password, reset it. For more information, see Change or reset the password.