Using the BigAnimal CLI

Suggest edits

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

Setting	Description
`context_credential`	The default credential used in the following commands.
`context_project`	The default project used to run the following commands.
`output_mode`	The command line output format: table, json, xml, or yaml.
`confirm_mode`	If enabled, create/update/delete commands require user confirmation.
`interactive_mode`	If enabled, CLI prompts for missing flags and available options. See Interactive mode for more information.
`check_update_mode`	If enabled, CLI detects new updates and prompts for download.
`warning_mode`	If 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:

← Prev

Using the BigAnimal API

↑ Up

Using the API and CLI

Managing clusters using the CLI

Using the BigAnimal CLI

Installing the CLI

Download the binary executable

(Optional) Validate the download

Make the CLI command executable within Cloud Shell

Authenticating user using access key

Importing access key

Note

Setting access key environment variable

Switching access keys

Authenticating as a valid user

Creating credentials for an alternative organization

Configuring

Available configuration settings

Usability features

Online command reference and help

Interactive mode

Sample use cases

← Prev

↑ Up

Next →