Installing and running the Workbench CLI
Prior reading: Overview of the Command Line Interface
Purpose: This document provides detailed instructions for installing the Workbench CLI package and using the Verily Workbench Command Line Interface.
Important note: If you are using the CLI on a cloud environment in Verily Workbench, you do not need to install anything; all relevant packages are already installed by default in your environment.
- Java 17 or greater
- Docker 20.10.2 (Must be running if installing in DOCKER_AVAILABLE mode)
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 hood to pull the default Docker image from the Google Container Repository (GCR); therefore,
gcloud is required for installation.
terra app commands from anywhere other than a cloud environment in Workbench, 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 versionto verify the installation.
gsutil- This is included in the
gcloudCLI, or available separately here. Verify its installation with
gsutil version(also printed as part of
bq- This is included with
gcloud. More details are available here. Similarly, verify its installation with
nextflow- Install by downloading a
bashscript and running it locally. Create a
nextflowdirectory somewhere convenient (e.g.
$HOME/nextflow) and switch to it. Then run
curl -s https://get.nextflow.io | bash. Finally, move the
nextflowexecutable script to a location on the
sudo mv nextflow /usr/local/bin/. Verify the installation with
git- Follow instruction here for installing Git on your platform.
Installing those packages will make the applications available in
terra by running, for example,
terra gsutil ls. When these tools are run through
terra, environment variables are set based on resources in the active workspace, and context such as the active GCP project is set up automatically.
Note: As noted above, if you are using the CLI on a cloud environment in Workbench, you do not need to run any of those commands; those packages are already installed by default.
By default, the CLI will be installed without support for Docker, meaning it won’t pull the Docker image.
If you wish to install with Docker support, set the TERRA_CLI_DOCKER_MODE environment variable to one of the following:
- DOCKER_NOT_AVAILABLE (default) to skip pulling the Docker image.
- DOCKER_AVAILABLE to pull the image (requires Docker to be installed and running)
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 # Set the Workbench CLI to talk to the Verily production environment (as opposed to a test environment): terra server set --name=verily --quiet
Re-installing or updating to the latest version
To update the Workbench CLI package, simply run the initial installation commands again.
Re-installing the Workbench CLI package will overwrite any existing installation, meaning that all JARs and scripts will be overwritten, but it will not modify your
$PATH. If you have added the location of the Workbench CLI to your
$PATH, you will therefore need to ensure its location is up to date in your path again after each install.
Using a specific version
To install a specific version, run this command before running the ‘first installation’ commands, first editing it for the version that you wan to use:
Make sure to change the version number provided in the example to the specific version you want to install.
Updating to the latest version in your cloud environment
To update the Workbench CLI package in your cloud environment, you’ll need to open a terminal. Then, run these commands:
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 mv terra $HOME/.local/bin # Set the authentication mechanism to 'manual' as your cloud environment does not have an internet browser. terra config set browser MANUAL # Re-authenticate, following the prompt. terra auth login # Provide a workspace to which to point the workpace context, which has been reset. terra workspace set --id=<YOUR_WORKSPACE_ID>
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)
Application exit codes will be passed through to the caller. For example, if
gcloud --malformedOption returns exit code
terra gcloud --malformedOption will also return exit code
If you are running the Workbench CLI from anywhere other than a cloud environment in Workbench, you must authenticate yourself.
The following command launches an OAuth flow that creates a new tab in your web browser window where you will complete the login process:
terra auth login
If the machine where you’re running the CLI does not have a web browser available to it, run the following commands instead:
terra config set browser MANUAL terra auth login
This will trigger the use of a manual login flow that does not involve the web browser.
Note: If you are using the CLI on a cloud environment in Workbench, you do not need to run any of those commands; you are already logged in by default when you open the cloud environment. You can verify this by running
terra auth status.
In order to perform any operations that incur a cost on Workbench (e.g. creating a workspace and resources within it), you need access to a billing account via a spend profile. An administrator (user with admin permissions) can grant you access.
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.
To learn more about sharing resources with other users, see Access control and sharing.
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
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
Last Modified: 16 November 2023