Using the BigAnimal CLI

Use the command line interface (CLI) for BigAnimal management activities, such as cluster provisioning and getting cluster status from your terminal. The CLI is an efficient way to integrate with BigAnimal and enables system administrators and developers to script and automate the BigAnimal 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:

    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 BigAnimal 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:
      echo "$(<biganimal_linux_amd64.sha256) biganimal" | sha256sum --check
  • For Windows users:

    1. Download the SHA256 checksum code for Windows distribution from the BigAnimal 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:
      CertUtil -hashfile biganimal.exe SHA256 type biganiml_windows_amd64.sha256
  • For MacOS users:

    1. Download the SHA256 checksum code for MacOS distribution from the BigAnimal 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:
      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 BigAnimal resources. We recommend that you use the access key authentication method.

BigAnimal 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>
Output
Access key "ba-user-1" is imported, operation succeeded
Switched the context credential to "ba-user-1".
Note

Avoid adding an access key by way of the import-access-key command as plain text in flag mode. Instead you can use:

biganimal credential import-access-key --name <name> --access-key $(< file_contains_the_key.txt)

Or, to avoid leaking the key into your shell command history, you can use interactive mode.

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

biganimal credential import-access-key
? Credential Name: ba-user-2
? Access Key: ******************************************************
Output
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 BigAnimal, you need to authenticate as a valid BigAnimal user. Use the credential create command to authenticate through the BigAnimal website and assign a refresh token and an access token to a local credential. For example:

biganimal credential create\
  --name "ba-user1"
Output
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 BigAnimal website and receive a new refresh token:

biganimal credential reset ba-user1
Output
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 BigAnimal 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
Output
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 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 BigAnimal 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 BigAnimal portal.

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:

    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:

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

You can verify the operation using credential show:

biganimal credential show
Output
┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 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

SettingDescription
context_credentialThe default credential used in the following commands.
context_projectThe default project used to run the following commands.
output_modeThe command line output format: table, json, xml, or yaml.
confirm_modeIf enabled, create/update/delete commands require user confirmation.
interactive_modeIf enabled, CLI prompts for missing flags and available options. See Interactive mode for more information.
check_update_modeIf enabled, CLI detects new updates and prompts for download.
warning_modeIf enabled, CLI displays warning messages.

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: