ScaleGrid CLI Tool for Redis™ Installation & Use

See how to leverage command line interface (CLI) functionality for our hosting for Redis™* service. This ScaleGrid tool allows you to perform the same actions you can through the console from the command line.

The ScaleGrid CLI tool is written in Python and published as a Python package, and the package simply needs to be installed into your machine from the Package Index. The CLI currently supports generic Redis-specific and MongoDB-specific commands, and support for other database types will be added in the future.

ScaleGrid CLI Tool for Redis™ Installation

  1. This package requires Python>=3.6, and you can follow these steps to install Python.

  2. Installing the package is straightforward – run pip install scalegrid_cli.

  1. You must login to your ScaleGrid account before you can perform any of the actions. This can be done by running sg-cli login from the CLI.

  2. You will be prompted to enter your email address, password and 2FA code. Upon successful authentication, a cookie will be setup for the session and you will be logged in.

👍

You will now be able to perform actions on your Redis™ clusters from the CLI!

Now that you can perform actions on your Redis™ clusters from the CLI, you can list all the Redis™ clusters in your account by running sg-cli redis list-clusters. If you have any Redis™ clusters in your account, the output will look something like below:

To logout from your account, run sg-cli logout.

CLI Command Examples

The following actions can be performed from the command line:

Help Commands

Description: Help menu
Full Command (usage):

sg-cli --help

Output (expected):
ScaleGrid Help Menu

Usage:
    sg-cli [redis] <command> [<args>...]

Options:
    -v, --verbose  Increase verbosity
    -h, --help     Show this menu
    -V --version   Show version

Commands:
    (redis) add-firewall-rules
    check-job-status
    (redis) create-alert-rule
    (redis) create-cloud-profile
    (redis) create-cluster
    (redis) delete-backup
    delete-alert-rule
    delete-cloud-profile
    (redis) delete-cluster
    (redis) get-active-alerts
    (redis) get-cluster-credentials
    (redis) list-alert-rules
    (redis) list-backups
    list-cloud-profiles
    (redis) list-clusters
    login
    logout
    (redis) patch-os
    (redis) pause-cluster
    (redis) peek-at-backup
    (redis) resolve-alerts
    (redis) restore-backup
    (redis) resume-cluster
    (redis) scale-up
    (redis) set-backup-schedule
    (redis) start-backup
    update-cloud-profile-keys
    wait-until-job-done

Help commands:
    sg-cli -h
    sg-cli <command> -h
    sg-cli (redis) -h
    sg-cli [redis] <command> -h

You can also run sg-cli -h from the for a detailed help menu for the particular command.

Example:

$ sg-cli redis add-firewall-rules -h

Login Command

Description: Login to your ScaleGrid account
Full Command: (You will be prompted for your password and 2FA code)

sg-cli login --email <YourEmailAddress>

Output:

INFO Connection successful, setting up cookie
INFO Cookie created successfully

Create Cloud Profile Command

Description: Create a cloud profile
AWS Full Command:

sg-cli redis create-cloud-profile --aws --cloud-profile-name AWSRedisTestCP --region uswest1 --access-key <> --secret-key <> --vpc-id vpc-e0359578 --vpc-cidr 172.31.0.0/16 --subnet-id subnet-3254d7d1 --subnet-cidr 172.31.0.0/20 --security-group-name aws-private-sg --security-group-id sg-987r5l26

Azure Full Command:

sg-cli redis create-cloud-profile --azure --cloud-profile-name AzureRedisTestCP --region eastus --subscription-id <> --subnet-name subnet1-eastus --vnet-name vnet-aksd2497 --vnet-resource-group eastustest
 --security-group-name azure-private-sg

Output:

INFO New cloud profile ID: 3738. Keep this ID and use it to perform commands on your cloud profile once it is created.
INFO To get more information about your cloud profile once it is created, run the list-cloud-profiles command.
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385126

Create Redis™ Cluster Command

Description: Create a Standalone Cluster or Replica Set
Full Command:

sg-cli redis create-cluster --cluster-name TestCluster --shard-count 1 --server-count 1 --sentinel-count 0  --size micro --version V505  --cidr-lis 0.0.0.0/0 --machine-list AWSRedisTestCP --interval 12

Output:

INFO Cluster creation started successfully
INFO New cluster ID: 99999. Keep this ID and use it to perform commands on your cluster once it is created.
INFO To get more information about your cluster once it is created, run the list-clusters command.
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385127

Get Redis™ Cluster Credentials Command

Description: Get the password to access the database
Full Command:

sg-cli redis get-cluster-credentials --cluster-name TestCluster

Output:

INFO Username: None
INFO Password: KQYttYmANutDjP76T

List Redis™ Clusters Command

Description: Get a list of all your clusters of a specified database type
Full Command:

sg-cli redis list-clusters

Output:

{
    "name": "TestCluster",
    "id": 2132,
    "clusterType": "ReplicaSet",
    "shared": false,
    "status": "Running",
    "size": "Micro",
    "versionStr": "5.0.5",
    "shards": [
        {
            "redisServers": [
                {
                    "addressableName": "SG-TestCluster-31674.servers.mongodirector.com",
                    "diskSizeGB": 10,
                    "diskUsedGB": 1
                },
                {
                    "addressableName": "SG-TestCluster-31675.servers.mongodirector.com",
                    "diskSizeGB": 10,
                    "diskUsedGB": 1
                },
                {
                    "addressableName": "SG-TestCluster-31676.servers.mongodirector.com",
                    "diskSizeGB": 0,
                    "diskUsedGB": 0
                }
            ]
        }
    ],
    "encryptionEnabled": true
}

Start Backup Command

Description: Create a backup of a cluster
Full Command:

sg-cli redis start-backup --cluster-name TestCluster --backup-name BatchBackup

Output:

INFO TestCluster backup started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385129

List Backups Command

Description: Get a list of backups of a specified cluster
Full Command:

sg-cli redis list-backups --cluster-name TestCluster

Output:

{
    "comment": "",
    "created": 1583202217000,
    "entityId": 1328945,
    "geoLocation": null,
    "id": 1328945,
    "location": "{\"ID\":\"snap-0e4dca60c11b6d235\",\"region\":\"useast1\",\"sizeInGB\":10,\"slots\":null}",
    "longlocation": null,
    "name": "BatchBackup",
    "object_id": 99999,
    "object_type": "RedisCluster",
    "persistent": true,
    "size": 0,
    "type": "ONDEMAND",
    "updated": 1583202217000
}

Restore Backup Command

Description: Restore a backup
Full Command:

sg-cli redis restore-backup --cluster-name TestCluster --backup-name BatchBackup

Output:

INFO BatchBackup restore started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385134

Set Backup Schedule Command

Description: Change the backup schedule of a cluster
Full Command:

sg-cli redis set-backup-schedule --cluster-name TestCluster --enabled --interval 24 --hour 0 --limit 2

Output:

INFO Backup schedule changed successfully

Get Backup Schedule Command

Description: Get the backup schedule of a cluster
Full Command:

sg-cli redis get-backup-schedule --cluster-name TestCluster

Output:

INFO Backup hour: 1
INFO Backup interval in hours: 12
INFO Backups retention limit: 30
INFO Backup target: SLAVE

Create Alert Rule Command

Description: Create an alert rule for a particular cluster
Full Command:

sg-cli redis create-alert-rule --cluster-name TestCluster --type metric --operator lt --threshold 100 --notifications email --metric cpu_user --duration two

Output:

{
    "alertRuleDescription": "CPU - User (%) less than 100%",
    "averageType": "TWO",
    "clusterId": 99999,
    "created": "2020-03-04 02:29:33.440000",
    "databaseType": "REDIS",
    "enabled": true,
    "id": 919,
    "metric": "CPU_USER",
    "notifications": [
        "EMAIL"
    ],
    "operator": "LT",
    "ruleMetricName": "CPU - User (%)",
    "threshold": 100.0,
    "type": "METRIC"
}
INFO Alert rule created successfully

Peek at Backup Command

Description: Create a new standalone cluster from a past backup
Full Command:

sg-cli redis peek-at-backup --cluster-name TestCluster --backup-name BatchBackup --new-name BatchPeek

Output:

INFO Peek started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385139

Get Active Alerts Command

Description: Get all active alerts on a particular cluster
Full Command:

sg-cli redis get-active-alerts --cluster-name TestCluster

Output:

{
    "alertDescription": "CPU - User (%) went below 100%",
    "clusterID": 99999,
    "created": "2020-03-04 02:30:24",
    "dismissComment": null,
    "dismissedDate": null,
    "id": 114389,
    "machineName": "SG-TestCluster-12345.servers.mongodirector.com",
    "state": "ACTIVE",
    "userAlertRuleId": 919
}

Resolve Alerts Command

Description: Dismiss alerts for a particular cluster
Full Command:

sg-cli redis resolve-alerts --cluster-name TestCluster --alert-id-list 114389

Output:

INFO Alerts resolved successfully

List Alert Rules Command

Description: List all the alert rules for a particular cluster
Full Command:

sg-cli redis list-alert-rules --cluster-name TestCluster

Output:

{
    "alertRuleDescription": "CPU - User (%) less than 100%",
    "averageType": "TWO",
    "clusterId": 99999,
    "created": "2020-03-04 02:29:33",
    "databaseType": "REDIS",
    "enabled": true,
    "id": 919,
    "metric": "CPU_USER",
    "notifications": [
        "EMAIL"
    ],
    "operator": "LT",
    "ruleMetricName": "CPU - User (%)",
    "threshold": 100.0,
    "type": "METRIC"
}

Delete Alert Rule Command

Description: Delete an alert rule from a particular cluster
Full Command:

sg-cli delete-alert-rule --alert-rule-id 919

Output:

INFO Alert rule deleted successfully

Scale Up Command

Description: Increase the size of your cluster
Full Command:

sg-cli redis scale-up --cluster-name TestCluster --size Small

Output:

INFO Scale up started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385210

Pause Cluster Command

Description: Pause a cluster
Full Command:

sg-cli redis pause-cluster --cluster-name TestCluster

Output:

INFO Pause started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385217

Resume Cluster Command

Description: Resume a cluster
Full Command:

sg-cli redis resume-cluster --cluster-name TestCluster

Output:

INFO Resume started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385220

Patch OS Command

Description: Patch your OS with the most recent updates
Full Command:

sg-cli redis patch-os --cluster-name BatchPeek

Output:

INFO OS Patch started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385224

Delete Cluster Command

Description: Delete an old cluster
Full Command:

sg-cli redis delete-cluster --cluster-name TestCluster

Output:

INFO Cluster delete started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385232

Add Firewall Rules Command

Description: Add a list of IP CIDR to the firewall rules of your cluster
Full Command:

sg-cli redis add-firewall-rules --cluster-name TestCluster --cidr-list 10.20.0.0/16,10.30.0.0/20

Output:

INFO Firewall rules added successfully

Delete Backup Command

Description: Delete an old backup
Full Command:

sg-cli redis delete-backup --cluster-name TestCluster --backup-name BatchBackup

Output:

INFO Backup Delete started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385237

Update Cloud Profile Keys Command

Description: Update Keys in AWS Cloud Profile
Full Command:

sg-cli update-cloud-profile-keys --cloud-profile-name AWSRedisTestCP --access-key <> --secret-key <>

Output:

INFO AWS cloud profile keys updated successfully

List Cloud Profiles Command

Description: Get a list of all your cloud profiles
Full Command:

sg-cli list-cloud-profiles

Output:

{
    "providerMachinePoolName": "SYSTEM (REDIS-AWS) - US East (N. Virginia)",
    "regionDesc": "US East (N. Virginia)",
    "region": "useast1",
    "id": 1616,
    "dbType": "REDIS",
    "type": "EC2",
    "created": "2016-10-23 07:17:45",
    "owner": "[email protected]",
    "status": "Running",
    "shared": true
}
{
    "providerMachinePoolName": "SYSTEM (REDIS-AWS) - US East (Ohio)",
    "regionDesc": "US East (Ohio)",
    "region": "useast2",
    "id": 1683,
    "dbType": "REDIS",
    "type": "EC2",
    "created": "2017-01-08 02:31:33",
    "owner": "[email protected]",
    "status": "Running",
    "shared": true
}

Delete Cloud Profile Command

Description: Delete a cloud profile
Full Command:

sg-cli delete-cloud-profile --cloud-profile-name AWSRedisTestCP

Output:

INFO Cloud profile delete started successfully
INFO Use your action ID to monitor the job status.
INFO Action ID: 1385243

Logout Command

Description: Logout of your ScaleGrid account
Full Command:

sg-cli logout

Output:

INFO Cookie removed, logging out…

Test The Commands

The below workflow can be run in a batch file to test out all the commands supported by the CLI - login, create cloud profile, create cluster, get cluster credentials, etc. Assign the necessary values to each flag to ensure that the commands run successfully. The command prompt closes if there is an error in a call and you can find the full traceback in the log file in your home path.

@echo off
:: Set values for the below variables so they can be used later in the commands
set cpname=<CloudProfileName>
set clustername=<ClusterName>
set peekedclustername=<PeekAtBackupClusterName>
set backupname=<BackupName>
set accesskey=<AWSAccessKey>
set secretkey=<AWSSecretKey>

:: To get the help menu
sg-cli --help

:: To login to your ScaleGrid account
sg-cli login --email <YourEmailAddress>

:: To create an AWS cloud profile, enter the value for each flag
sg-cli redis create-cloud-profile --aws --cloud-profile-name %cpname% --region uswest1 --access-key %accesskey% --secret-key %secretkey% --vpc-id <VPCID> --vpc-cidr x.x.x.x/x --subnet-id <SubnetID> --subnet-cidr x.x.x.x/x --security-group-name <SGName> --security-group-id <SGID>
CALL :wait

:: To create a Redis™ cluster, enter the name of the cloud profile being created in the previous step
sg-cli redis create-cluster --cluster-name %clustername% --shard-count 1 --server-count 1 --sentinel-count 0  --size micro --version V505  --cidr-list 0.0.0.0/0 --machine-list %cpname% --interval 12
CALL :wait

:: To get admin credentials for newly created cluster
sg-cli redis get-cluster-credentials --cluster-name %clustername%

:: To list the Redis™ clusters in your account
sg-cli redis list-clusters

:: To start a manual backup on your Redis™ cluster
sg-cli redis start-backup --cluster-name %clustername% --backup-name %backupname%

CALL :wait

:: To list the backups of your Redis™ cluster
sg-cli redis list-backups --cluster-name %clustername%

:: To restore your Redis™ cluster using the previously taken backup
sg-cli redis restore-backup --cluster-name %clustername% --backup-name %backupname%

:: To enable scheduled backup for your Redis™ cluster, at 00:00 everyday, with an interval of 24 hours and a maximum retention of 2 scheduled backups
sg-cli redis set-backup-schedule --cluster-name %clustername% --enabled --interval 24 --hour 0 --limit 2

:: To disable scheduled backup
sg-cli redis set-backup-schedule --cluster-name %clustername%

:: To get the backup schedule for your Redis™ cluster
sg-cli redis get-backup-schedule --cluster-name %clustername%

:: To create an alert rule for your Redis™ cluster, the below rule will trigger an alert whenever the CPU is greater than 80% for a duration of 2 minutes
sg-cli redis create-alert-rule --cluster-name %clustername% --type metric --operator gt --threshold 80 --notifications email --metric cpu_user --duration two
CALL :getAlertRule

:: To create a peek at backup cluster for your Redis™ cluster
sg-cli redis peek-at-backup --cluster-name %clustername% --backup-name %backupname% --new-name %peekedclustername%
CALL :wait

:: To get active alert rules for your Redis™ cluster
sg-cli redis get-active-alerts --cluster-name %clustername%
CALL :getAlert

:: To manually resolve alerts for your Redis™ cluster
sg-cli redis resolve-alerts --cluster-name %clustername% --alert-id-list %alertID%

:: To list all alert rules for your Redis™ cluster
sg-cli redis list-alert-rules --cluster-name %clustername%

:: To delete an alert rule for your Redis™ cluster, uncomment the command to run
:: sg-cli delete-alert-rule --alert-rule-id %ruleID%

:: To scale up your Redis™ cluster
sg-cli redis scale-up --cluster-name %clustername% --size Small
CALL :wait

:: To pause your Redis™ cluster
sg-cli redis pause-cluster --cluster-name %clustername%
CALL :wait

:: To resume your Redis™ cluster
sg-cli redis resume-cluster --cluster-name %clustername%
CALL :wait

:: To patch the OS of your Redis™ cluster
sg-cli redis patch-os --cluster-name %peekedclustername%
CALL :wait

:: To delete your Redis™ peek at backup cluster, uncomment the command to run
:: sg-cli redis delete-cluster --cluster-name %peekedclustername%
CALL :wait

:: To add a list of IP CIDRs to whitelist to your Redis™ cluster
sg-cli redis add-firewall-rules --cluster-name %clustername% --cidr-list x.x.x.x/x,x.x.x.x/x

:: To delete the backup of your Redis™ cluster, uncomment the command to run
:: sg-cli redis delete-backup --cluster-name %clustername% --backup-name %backupname%
CALL :wait

:: To permanently delete your Redis™ cluster, uncomment the command to run
:: sg-cli redis delete-cluster --cluster-name %clustername%
CALL :wait

:: To update your cloud profile keys with new credentials, uncomment the command to run
:: sg-cli update-cloud-profile-keys --cloud-profile-name %cpname% --access-key xxxxxxxxxxxxxxxxxxxxx --secret-key xxxxxxxxxxxxxxxxxxxxx

:: To list all cloud profiles in your ScaleGrid account
sg-cli list-cloud-profiles

:: To delete a cloud profile from your ScaleGrid account, uncomment the command to run
:: sg-cli delete-cloud-profile --cloud-profile-name %cpname%

:: To logout from your ScaleGrid account
sg-cli logout

EXIT /B %ERRORLEVEL%

:: Calling the below function waits for the action to complete. It can be used for actions that are async operations, i.e., actions that return an action ID
:wait
@echo off
:: Log file is created inside the .sg directory of your home directory
for /f "tokens=11" %%i in (%UserProfile%\.sg\sg.log) do ^
set ID=%%i
@echo on
sg-cli wait-until-job-done --action-id %ID%
EXIT /B 0

:getAlertRule
@echo off
for /f "tokens=12" %%i in (%UserProfile%\.sg\sg.log) do ^
set ruleID=%%i
@echo on
EXIT /B 0

:getAlert
@echo off
for /f "tokens=11" %%i in (%UserProfile%\.sg\sg.log) do ^
set alertID=%%i
@echo on
EXIT /B 0

* Redis is a trademark of Redis Labs Ltd. Any rights therein are reserved to Redis Labs Ltd. Any use by ScaleGrid is for referential purposes only and does not indicate any sponsorship, endorsement or affiliation between Redis and ScaleGrid.