Installing and running the Workbench CLI

Install and run

To install the latest version:

curl -L https://storage.googleapis.com/workbench-public/workbench-cli/download-install.sh | bash && export SUPPRESS_GCLOUD_CREDS_WARNING=true

# Optional: Move to somewhere in PATH
sudo mv terra /usr/local/bin

# Talk to Verily production environment (as opposed to a test environment):
terra server set --name=verily --quiet

To install a specific version, run before above commands: export TERRA_CLI_VERSION=0.409.0

By default, the CLI will be installed without support for Docker (i.e. it won’t pull the Docker image). The TERRA_CLI_DOCKER_MODE environment variable controls Docker support. Set it to

• DOCKER_NOT_AVAILABLE (default) to skip pulling the Docker image
• DOCKER_AVAILABLE to pull the image (requires Docker to be installed and running).

Re-installing will overwrite any existing installation (i.e. all JARs and scripts will be overwritten), but will not modify the $PATH. If you have added the location of the Workbench CLI to your $PATH, you will therefore need to add its location to your path again after each install.

Requirements

1. Java 17 or greater
2. Docker 20.10.2 (Must be running if installing in DOCKER_AVAILABLE mode)
3. curl, tar, gcloud (For install only)

Note: The CLI doesn’t use gcloud directly either during installation or normal operation. However, docker pull may use gcloud under the covers to pull the default Docker image from GCR; therefore, gcloud is required for installation.

Login

Note: If you are using the CLI on a cloud environment, you do not need to run the commands below. You are already logged in. You can verify this by running terra auth status.

1. terra auth login launches an OAuth flow that creates a new tab in your browser window where you will complete the login.
2. If the machine where you’re running the CLI does not have a browser available to it, then use the manual login flow by setting the browser flag using terra config set browser MANUAL. See the Authentication section below for more details.

Spend profile access

In order to spend money on Verily Workbench (e.g. by creating a workspace and resources within it), you need access to a billing account via a spend profile. An admin user can grant you access. Admins, see ADMIN.md for more details.

External data

In order to read data from or write data to a private external resource from Workbench, you must grant the appropriate data access permissions to your proxy-group. Run terra auth status to view the email address of your proxy group.

Local tools installation

When running terra app commands in LOCAL_PROCESS app-launch mode (the default), it’s necessary to install various tools locally. The following instructions are for both MacOS and Linux.

• gcloud - Make sure you have Python installed, then download the .tar.gz archive file from the installation page. Run gcloud version to verify the installation.
• gsutil - This is included in the gcloud CLI, or available separately here. Verify its installation with gsutil version (also printed as part of gcloud version)
• bq - This is included with gcloud. More details are available here. Similarly, verify its installation with bq version.
• nextflow - Install by downloading a bash script and running it locally. Create a nextflow directory somewhere convenient (e.g. $HOME/nextflow) and switch to it. Then run curl -s https://get.nextflow.io | bash. Finally, move the nextflow executable script to a location on the $PATH by running sudo mv nextflow /usr/local/bin/. Verify the installation with nextflow -version.
• git - Follow instruction here for installing Git on your platform.

Now, these applications are available in terra by running, for example, terra gsutil ls. When run with terra, environment variables are set based on resources in the active workspace, and context such as the active GCP project is set up automatically.

Troubleshooting

Clear context

Clear the context file and all credentials. This will require you to login and select a workspace again.

cd $HOME/.terra
rm context.json
rm StoredCredential

Uninstalling

There is not yet an uninstaller. You can clear the entire context directory, which includes the context file, all credentials, and all JARs. This will then require a re-install (see above).

rm -R $HOME/.terra

Exit codes

The CLI sets the process exit code as follows.

• 0 = Successful program execution
• 1 = User-actionable error (e.g. missing parameter, workspace not defined in the current context)
• 2 = System or internal error (e.g. error making a request to a Workbench service)
• 3 = Unexpected error (e.g. null pointer exception)

App exit codes will be passed through to the caller. e.g. If gcloud --malformedOption returns exit code 2, then terra gcloud --malformedOption will also return exit code 2.