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
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.
- 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
docker pull may use
under the covers to pull the default Docker image from GCR; therefore,
gcloud is required for installation.
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.
terra auth loginlaunches an OAuth flow that creates a new tab in your browser window where you will complete the login.
- 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
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.
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.
terra auth status to view the email address of your proxy group.
Local tools installation
terra app commands in
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 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.
Now, these applications are available in
terra by running, for
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.
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
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.
gcloud --malformedOption returns exit code
terra gcloud --malformedOption will also return exit code
Last Modified: 16 November 2023