Optable CLI

Using the Optable DCN command line tools

What is Optable CLI?

The Optable CLI (Command Line Interface) is a utility designed to enable an Optable data collaboration node (DCN) administrator to interact with the DCN and perform management tasks which would otherwise be done using the web-based DCN UI.

Who Should Use Optable CLI?

Using the Optable CLI requires authenticating to an Optable data collaboration node (DCN). The CLI is therefore designed to be used by DCN customers.

Downloading Optable CLI

The latest version of the Optable CLI can be downloaded from Optable's CDN:

Platform	Download Link
OS X (64-bit)	Latest build for Darwin 64-bit
Windows (64-bit)	Latest build for Windows 64-bit
Linux (64-bit)	Latest build for Linux 64-bit

Note that on OS X you may need to download the executable with curl instead of your browser in order to be able to execute it:

curl https://cdn.optable.co/cli/latest/optable-cli-darwin --output optable-cli

Note that on OS X or Linux you may need to chmod +x ./optable-cli before you can run the executable with ./optable-cli

Warning: v9.11.0 of the Optable CLI introduces changes to the export commands: before, you could invoke the create command using ./optable-cli export create [args] and now you should add file to create an export to a file (using Google Cloud Storage or Amazon S3 as storage), like this: ./optable-cli export create file [args]. The export object has been changed to wrap all file-specific fields into the attribute file. In a future release, the file-specific fields on the export object will be removed in favour of those wrapped in export.file. The fields being moved are the following: filename, override_existing, export_metadata, id_format, cluster_format. Each can be found in export.file object, for example export.file.filename, export.file.override_existing, etc. Update your CLI to v9.11.0 before November 2022 as we will be deprecating the previous export commands then.

Using Optable CLI

Optable CLI commands require authentication with a DCN user or service account. You can create and manage accounts from the Admin > Accounts section in your DCN UI.

Logging In With a User Account

You can login with your personal DCN user account by running optable-cli login <dcn-hostname>

The specified dcn-hostname should just be the hostname of your data collaboration node, without any protocol prefix. For example, if you login to your DCN UI by browsing to https://my-dcn.cloud.optable.co/admin, then your DCN hostname is just my-dcn.cloud.optable.co

A browser window will open automatically in which you will be able to authenticate using one of the methods described in the Authentication section.

Note that the CLI will automatically refresh your session but will require to manually relogin after 30 days of inactivity.

Logging In With a Service Account

If you want to script using the CLI, it's recommended to authenticate using a service account instead of your personal user account. Logging into a service account has the advantage of not expiring and not requiring re-authentication.

You can create a service account from the Admin > Accounts section in your DCN UI. Once created, you will be able to create a service key and download a JSON file embedding a private key.

Be sure to keep service account private key files protected as they contain authentication secrets!

You can run the optable-cli activate-service-account <path-to-key-file> command to add the service account private key file to the CLI configuration. You can then run CLI commands as the service account.

Note that the DCN only stores the public key corresponding to the service key which you have created. The private key is stored on the client side in the CLI configuration ($HOME/.config/optable by default). The private key is used to sign each request sent to the DCN.

If you suspect that your private key has been compromised, you can revoke a service key from the DCN UI by navigating to the service account in Admin > Accounts.

Help on Commands

You can get a list of all supported commands by running optable-cli --help

To get help on a specific command, run optable-cli <command> --help

DCN Contexts

You can connect to multiple DCNs using the CLI. When you login with the CLI as explained further above, the default context is used. If you would like to login to another DCN you can pass the -c <context-name> option to optable-cli when logging in.