Using the Cloud Service CLI

Use the command line interface (CLI) for Cloud Service management activities, such as cluster provisioning and getting cluster status from your terminal. The CLI is an efficient way to integrate with Cloud Service and enables system administrators and developers to script and automate the Cloud Service administrative operations.

Installing the CLI

The CLI is available for Linux, MacOS, and Windows operating systems.

Download the binary executable

• For Linux operating systems, use the following command to get the latest version of the binary executable:

  → WrapCopy

  curl -LO "https://cli.biganimal.com/download/$(uname -s)/$(uname -m)/latest/biganimal"

• For all other operating systems, download the executable binary here. After downloading, move the binary executable under a directory on your executable search path.

(Optional) Validate the download

• For Linux users:

  1. Copy the SHA256 checksum code for Linux distribution from the Cloud Service CLI page and store it as a local file, such as biganimal_linux_amd64.sha256. Alternatively, click the SHA256 code to download it as a file directly and verify the content of the downloaded file is identical to the checksum code showed on the page.
  2. From your local shell, validate the binary executable file against the checksum file:

     → WrapCopy

     echo "$(<biganimal_linux_amd64.sha256) biganimal" | sha256sum --check

• For Windows users:

  1. Download the SHA256 checksum code for Windows distribution from the Cloud Service CLI page and store it as a local file, such as biganimal_windows_amd64.sha256. Alternatively, click the SHA256 code to download it as a file directly and verify the content of the downloaded file is identical to the checksum code showed on the page.
  2. Validate the binary executable file against the checksum file using CertUtil:

     → WrapCopy

     CertUtil -hashfile biganimal.exe SHA256 type biganiml_windows_amd64.sha256

• For MacOS users:

  1. Download the SHA256 checksum code for MacOS distribution from the Cloud Service CLI page and store it as a local file, such as biganimal_darwin_amd64.sha256. Alternatively, click the SHA256 code to download it as a file directly and verify the content of the downloaded file is identical to the checksum code showed on the page.
  2. From MacOS terminal, validate the binary executable file against the checksum file:

     → WrapCopy

     echo "$(<biganimal_darwin_amd64.sha256)  biganimal" | shasum -a256 -c

Make the CLI command executable within Cloud Shell

Change the permissions of the CLI to make it executable in Cloud Shell:

chmod +x biganimal

Authenticating user using access key

You can create and manage login credentials using an access key that allows users to access Cloud Service resources. We recommend that you use the access key authentication method.

Cloud Service CLI provides the following access key operations.

Importing access key

This command supports two modes: flag mode and interactive mode.

This example shows how to import an access key in flag mode:

biganimal credential import-access-key --name ba-user-1 --access-key <your-key>

Access key "ba-user-1" is imported, operation succeeded
Switched the context credential to "ba-user-1".

This example shows how to import an access key in interactive mode:

biganimal credential import-access-key
? Credential Name: ba-user-2
? Access Key: ******************************************************

Access key "ba-user-2" is imported, operation succeeded
Switched the context credential to "ba-user-2".

Setting access key environment variable

You can configure an environment variable BA_ACCESS_KEY. This setting overrides the default context credential. If you want to use the default context credential, then remove this environment variable, or set it to "".

Switching access keys

You can import multiple access keys and then set one key as the default context credential for all commands. Use credential show to list all available credentials, and use config set context_credential to set a default credential.

Authenticating as a valid user

Before using the CLI to manage Cloud Service, you need to authenticate as a valid Cloud Service user. Use the credential create command to authenticate through the Cloud Service website and assign a refresh token and an access token to a local credential. For example:

biganimal credential create\
  --name "ba-user1"

Querying Authentication Endpoint for 'portal.biganimal.com'
First, copy your one-time code:
         CWWG-SMXC
Then visit: https://auth.biganimal.com/activate
press [Enter] to continue in the web browser...

Credential "ba-user1" created!

Refresh tokens expire after 30 days. To continue using the credential to access the CLI, use the credential reset command to authenticate through the Cloud Service website and receive a new refresh token:

biganimal credential reset ba-user1

Visit this URL to login: https://auth.biganimal.com/activate?user_code=****-****
or press [Enter] to continue in the web browser 

Credential "ba-user1" reset operation succeeded

You can create multiple credentials for different Cloud Service accounts and then set one as context of your current management session. Use credential show to list all available credentials, and use config set context_credential to set a default credential for the current context. For example:

biganimal credential show

┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Credentials                                                                                                  │
├──────────────┬──────────────┬─────────────────┬──────────────────────┬──────────────────────┬──────┬─────────┤
│ name         │ type         │ key             │ organization         │ address              │ port │ context │
├──────────────┼──────────────┼─────────────────┼──────────────────────┼──────────────────────┼──────┼─────────┤
│ ba-user1     │ AccessKey    │ baak_1e2vAJO*** │                      │ portal.biganimal.com │ 443  │ x       │
│ ba-user2     │ ClassicToken │                 │ My_organization      │ portal.biganimal.com │ 443  │         │
└──────────────┴──────────────┴─────────────────┴──────────────────────┴──────────────────────┴──────┴─────────┘

biganimal config set context_credential ba-user1

Creating credentials for an alternative organization

The Cloud Service CLI supports the capability to create credentials for an alternative organization to which you have been invited or are already a member. You can invite users that have an EDB account to join an organization by selecting the Invite New User option on the Users page in the Console.

To create credentials for an alternative organization, you can use either interactive mode or specify the settings with flags on the command line:

• Select the organization from the list in interactive mode:

  → WrapCopy

  biganimal credential create

  Output

  ? Credential Name: ba-user2
  ? Organization:  [Use arrows to move, type to filter]
    My_Organization
  > My_Organization_2
     
  ? Organization: My_Organization_2
  Credential "ba-user2" is created operation succeeded
  Switched the context credential to "ba-user2".

• Specify the organization name in the credential create command:

  → WrapCopy

  biganimal credential create -name ba-user2 --organization "My_Organization_2"

You can verify the operation using credential show:

biganimal credential show

┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Credentials                                                                                                  │
├──────────────┬──────────────┬─────────────────┬──────────────────────┬──────────────────────┬──────┬─────────┤
│ name         │ type         │ key             │ organization         │ address              │ port │ context │
├──────────────┼──────────────┼─────────────────┼──────────────────────┼──────────────────────┼──────┼─────────┤
│ ba-user2     │ ClassicToken │                 │ org_aNR9SNuNcUN6vGSn │ portal.biganimal.com │ 443  │ x       │
└──────────────┴──────────────┴─────────────────┴──────────────────────┴──────────────────────┴──────┴─────────┘

Configuring

The initial running of the CLI creates a hidden configuration folder in your user root directory. For example, for Linux it’s ${HOME}/.edb-cli. The CLI persists the configuration file in this directory as well as the credentials.

Don’t edit files in this directory directly. Instead, use the config subcommand to list and update the configuration settings of the CLI. Use the following command to get detailed usage and available configurations information:

biganimal config

Available configuration settings

Usability features

Online command reference and help

Use the -h or --help flags for more information on the CLI commands. You can use these flags on the biganimal command to get a listing of all the available subcommands (biganimal -h) or on a subcommand to get information on that particular command (for example, biganimal create cluster -h).

Interactive mode

In interactive mode, the CLI prompts you for any missing mandatory flags and lists any available options for your current context. To enable interactive mode:

biganimal config set interactive_mode on

Sample use cases

See:

• Managing clusters with the CLI
• Accessing Cloud Service features with the CLI