Install and run the Workbench CLI

Prior reading: Command-line interface overview

Purpose: This document provides detailed instructions for installing the Workbench CLI package and using the Workbench Command Line Interface.

Installation

Install dependencies

The following dependencies are required to run the CLI on a local machine.

• Java 17
• gcloud
• jq

A variety of methods can be used to install these tools. The instructions below show valid paths for both MacOS and Linux.

MacOS

Using homebrew:

-- Install Google Cloud SDK
brew install google-cloud-sdk

-- Install Java 17 using sdkman
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk default java 17.0.11-tem

-- Verify Java is now set to 17
java --version

-- Install jq
brew install jq

Linux

sudo apt update

-- Install Java 17 using sdkman
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk default java 17.0.11-tem

-- Verify Java is now set to 17
java --version

-- Install jq
sudo apt install jq

First installation

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 wb /usr/local/bin

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. Make sure to change the version number provided in the example to the specific version you want to install:

export TERRA_CLI_VERSION=0.418.0

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 and 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 wb $HOME/.local/bin

# Set the authentication mechanism to 'MANUAL' as your cloud environment does not have an internet browser.
wb config set browser MANUAL

# Re-authenticate, following the prompt.
wb auth login

# Provide a workspace to which to point the workpace context, which has been reset.
wb workspace set --id=<YOUR_WORKSPACE_ID>

Tool dependencies

The following installation instructions are for both MacOS and Linux.

• gcloud - Make sure you have Python installed, then download the .tar.gz archive file from the Google Cloud CLI installation page. Run gcloud version to verify the installation.
• gsutil - This is included in the Google Cloud CLI, or available separately here. Verify its installation with gsutil version (also printed as part of gcloud version)
• bq - This is included with the Google Cloud CLI. 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.

Installing those packages will make the applications available in wb by running, for example, wb gsutil ls. When these tools are run through wb, environment variables are set based on resources in the active workspace, and context such as the active Google Cloud project is set automatically.

Running

Usage

For a list of available commands, please see the List of Commands. You can find context-specific CLI usage examples in the CLI Usage Examples section.

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)

Application exit codes will be passed through to the caller. For example, if gcloud --malformedOption returns exit code 2, then wb gcloud --malformedOption will also return exit code 2.

Access requirements

Login (authentication)

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:

wb 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:

wb config set browser MANUAL
wb auth login

This will trigger the use of a manual login flow that does not involve the web browser.

Billing

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.

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 wb 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.

Troubleshooting

Clear context

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

cd $HOME/.workbench
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 reinstall (see above).

rm -R $HOME/.workbench