redis-cli is a 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 machine and manage data.

The type of network used to connect to an ApsaraDB for Redis instance

Network type Description
VPC (recommended) A virtual private cloud (VPC) is a private network dedicated to your Alibaba Cloud account. VPCs are logically isolated from each other at Layer 2 and provide higher security and performance. When redis-cli is deployed on an ECS instance, you can connect to an ApsaraDB for Redis instance through a VPC to gain better security performance and reduce network latency.
Internet If you want to manage an ApsaraDB for Redis instance on an on-premises machine, you can deploy redis-cli on the machine and connect to the ApsaraDB for Redis instance over the Internet.
Note No traffic data is charged if you are connected to the ApsaraDB for Redis instance over the Internet. But the connection may be exposed to security risks. We recommend that you use a VPC to improve security.

Overview

  • redis-cli is a built-in command-line interface (CLI) of native Redis. You can deploy the tool on an ECS instance or an on-premises machine by installing Redis.
    Note In addition to redis-cli, you can also use Data Management Service (DMS) to connect to a database of an ApsaraDB for Redis instance without a client program. DMS provides a graphic user interface for database management. For more information, see Use DMS.
  • The redis-cli version can be different from the major version of the ApsaraDB for Redis instance.

Use redis-cli in Linux

  1. Install redis-cli. Skip this step if it is already installed.
    1. Log on to the machine on which you want to install redis-cli, such as an ECS instance or an on-premises machine.
    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 as an example to demonstrate the operations. You can also install other versions. For more information, see the Redis official website.
    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 where the Redis source code is decompressed. Compile and install Redis source code.
      cd redis-6.0.9&&make
      Note It takes two or three minutes to compile and install Redis.
  2. Perform the following operations based on the redis-cli installation location:
    Redis-cli Installation location Operations
    ECS instance (recommended)
    1. Make sure that the ECS instance and the ApsaraDB for Redis instance belong to the same VPC. They share the same VPC ID in the Basic Information section.
      Note
    2. Obtain the internal IP address of the ECS instance. For more information, see How do I query IP addresses of ECS instances.
    3. Add the internal IP address of the ECS instance to the whitelist of the ApsaraDB for Redis instance. For more information, see Configure an IP whitelist.
    On-premises machine
    1. By default, an ApsaraDB for Redis instance provides only an internal endpoint. You must apply for a public endpoint when you want to connect to an ApsaraDB for Redis instance over the Internet. For more information, see Apply for a public endpoint.
    2. Run the curl ipinfo.io |grep ip command on the on-premises machine to obtain the public IP address. The returned result is shown in the following figure.View public IP address results
    3. Add the public IP address of the on-premises machine to the whitelist of the ApsaraDB for Redis instance. For more information, see Configure an IP whitelist.
  3. Obtain the connection information and run the following command to connect to an ApsaraDB for Redis instance:
    src/redis-cli -h <hostname> -p <port> [-c]
    Table 1. Parameters
    Parameter Description Method
    <hostname> The endpoint of the ApsaraDB for Redis instance.
    • If you connect an ECS instance to the ApsaraDB for Redis instance through a VPC, you must obtain the internal endpoint of the ApsaraDB for Redis instance in the VPC.
    • If you connect an on-premises machine to the ApsaraDB for Redis instance over the Internet, you must 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. The default port number is 6379. You can also specify a custom port number. For more information, see Modify endpoints.
    -c Enable the cluster mode Add -c only when you connect to a cluster instance of ApsaraDB for Redis by using a private endpoint.
    Command example by using a default endpoint (Applicable to 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
    Command example for a direct connection (Applicable to scenarios where ApsaraDB for Redis instances are connected by using private endpoints.):
    src/redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379 -c
  4. Run the following command to verify the password:
    AUTH <password>
    Note If password-free access is enabled for the instance, you can skip this step to run Redis commands if you connect to the ApsaraDB for Redis instance through a VPC.
    <password>: the password of a specific account. The format of the password varies based on the account. If you forget your password, you can reset it. For more information, see Change or reset the password.
    • Default account (the account named after the instance ID): Directly enter the password.
    • New account: The format of the password must be <user>:<password>. For example, if the username of the custom account is testaccount and the password is Rp829dlwa, the database password is testaccount:Rp829dlwa.

    Examples:

    AUTH testaccount:Rp829dlwa
    If the password verification succeeds, the following result is returned:
    OK
    Note If an error occurs, see Common connection errors.
  5. After the verification is complete, you can run Redis commands. For example, run the DBSIZE command to query the number of keys in the current database.
    For more information about Redis commands supported by ApsaraDB for Redis, see Overview. For more information about all Redis commands and their usage, see the Redis official website.

Use redis-cli in Windows

Note Only the 64-bit Windows operating systems are supported.
  1. Install redis-cli. Skip this step if it is already installed.
    1. Log on to the machine on which you want to install redis-cli, such as an ECS instance or an on-premises machine.
    2. Download the Redis-x64-3.2.100.zip file.
      Note Redis 3.2 (the latest version) is used as an example to demonstrate the operations. You can also install other versions. For more information, see MicrosoftArchive-Redis.
    3. Decompress the Redis-x64-3.2.100.zip file to the directory where you want to install Redis. The D:\Redis-x64-3.2.100 directory is used in this example.
  2. Perform the following operations based on the redis-cli installation location:
    redis-cli installation location Operations
    ECS instance (recommended)
    1. Make sure that the ECS instance and the ApsaraDB for Redis instance belong to the same VPC. They share the same VPC ID in the Basic Information section.
      Note If they are deployed in different VPCs, you must change the VPC to which the ECS instance belongs. For more information, see Change the VPC of an ECS instance.
    2. Obtain the internal IP address of the ECS instance. For more information, see How do I query IP addresses of ECS instances.
    3. Add the internal IP address of the ECS instance to the whitelist of the ApsaraDB for Redis instance. For more information, see Configure an IP whitelist.
    On-premises machine
    1. By default, an ApsaraDB for Redis instance provides only an internal endpoint. You must apply for a public endpoint when you want to connect to an ApsaraDB for Redis instance over the Internet. For more information, see Apply for a public endpoint.
    2. On the on-premises machine, visit ipinfo to obtain the public IP address of the on-premises machine.
    3. Add the public IP address of the on-premises machine to the whitelist of the ApsaraDB for Redis instance. For more information, see Configure an IP whitelist.
  3. On the ECS instance or the on-premises machine where redis-cli is installed, press the Windows key + R key to open the Run dialog box, enter the cmd command, and then click OK.
    The Windows CLI is opened.
    Figure 1. Windows CLI
    Windows CLI
  4. Run the following command to access the directory where redis-cli is installed:
    cd /d <path>

    <path>: the full path of the directory where the Redis-x64-3.2.100.zip file is decompressed. D:\Redis-x64-3.2.100 is used in this example.

    Examples

    cd /d D:\Redis-x64-3.2.100
  5. Obtain the connection information and run the following command to connect to an ApsaraDB for Redis instance:
    redis-cli -h <hostname> -p <port> [-c]
    Table 2. Parameters
    Parameter Description Method
    <hostname> The endpoint of the ApsaraDB for Redis instance.
    • If you connect an ECS instance to the ApsaraDB for Redis instance through a VPC, you must obtain the internal endpoint of the ApsaraDB for Redis instance in the VPC.
    • If you connect an on-premises machine to the ApsaraDB for Redis instance over the Internet, you must 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. The default port number is 6379. You can also specify a custom port number. For more information, see Modify endpoints.
    -c Enable the cluster mode Add -c only when you connect to a cluster instance of ApsaraDB for Redis by using a private endpoint.
    Command example by using the default endpoint (Applicable to 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
    Command example for direct connections (Applicable to scenarios where an ApsaraDB for Redis instance is connected through a direct connection.):
    redis-cli -h r-bp1zxszhcgatnx****.redis.rds.aliyuncs.com -p 6379 -c
  6. Run the following command to verify the password:
    AUTH <password>
    Note If password-free access is enabled for the instance, you can skip this step to run Redis commands if you connect to the ApsaraDB for Redis instance through a VPC.
    <password>: the password of a specific account. The format of the password varies based on the account. If you forget your password, you can reset it. For more information, see Change or reset the password.
    • Default account (the account named after the instance ID): Directly enter the password.
    • New account: The format of the password must be <user>:<password>. For example, if the username of the custom account is testaccount and the password is Rp829dlwa, the database password is testaccount:Rp829dlwa.

    Examples:

    AUTH testaccount:Rp829dlwa
    If the password verification succeeds, the following result is returned:
    OK
    Note If an error occurs, see Common connection errors.
  7. After the verification is complete, you can run Redis commands. For example, run the DBSIZE command to query the number of keys in the current database.
    For more information about Redis commands supported by ApsaraDB for Redis, see Overview. For more information about all Redis commands and their usage, see the Redis official website.

Common connection errors

Note If the minor version of your instance is earlier than required, the returned error message may be misleading. We recommend that you upgrade your instance to the latest minor version. For more information, see Upgrade the minor version.
Error message Cause and solution
(error) ERR illegal address The whitelist setting is not configured as required. For more information, see Step 2 in Use redis-cli in Linux or Use redis-cli in Windows.
(error) ERR client ip is not in whitelist
(error) ERR invalid password The password is invalid. Make sure that you use the correct password in a valid format. The password format varies based on the selected account.
  • Default account (the account named after the instance ID): Directly enter the password.
  • New account: The format of the password must be <user>:<password>. For example, if you set the custom account name to testaccount and the password to Rp829dlwa, enter testaccount:Rp829dlwa as the password.
Note If you forget your password, you can reset it. For more information, see Change or reset the password.