Basic usage

Examples of typical operations performed via the Verily Workbench CLI.

Prior reading: Overview of the Command Line Interface

Purpose: This document provides summary examples of commands that may be used alone or in combination to perform typical operations using the Workbench CLI.


These instructions assume that you have already installed the Workbench CLI or are working in a cloud environment where it has been installed.

Starting a new work session

This is an example of the typical flow of operations when starting a new work session with the Workbench CLI.

Log in

Use this command to authorize the Workbench CLI to access the relevant APIs and data with user credentials.

wb auth login

ℹ️ wb auth login

Optionally, check the authentication status to confirm the login was successful.

wb auth status

ℹ️ wb auth status

Check server status

Use this command to check the status of the server and details of the current context.

wb server status

ℹ️ wb server status

List accessible workspaces

This command lists all workspaces that you (i.e. the logged-in user) have read or write access to.

wb workspace list

ℹ️ wb workspace list

Create a new workspace

Use this command to create a workspace as well as a Google project to back the workspace.

Note: Make sure to replace <my-workspace-id> and <my-workspace-name> with the desired ID and name (without brackets).

wb workspace create --id=<my-workspace-id> --name=<my-workspace-name>

ℹ️ wb workspace create

The --name=<my-workspace-name> argument is optional; if you do not include it, the system will assign a randomly generated unique identifier (UUID).

Optionally, you can use the wb status command to confirm that the workspace was created successfully.

wb status

ℹ️ wb status

Use an existing workspace

If you want to use an existing workspace, use the set command instead of create.

wb workspace set --id=<my-workspace-id>

ℹ️ wb workspace set

Note that in the Verily Workbench web UI, the overview page of a workspace includes a predetermined command that can be copied and pasted to set that workspace in the CLI.

Add a controlled resource

You can add a controlled BigQuery dataset, GCS bucket, GCP notebook, or GCP Dataproc cluster.

wb resource create

The following is an example of a GCS bucket controlled resource creation:

wb resource create gcs-bucket --id=scratch-data --description="Scratch space for working data."
Successfully added controlled GCS bucket.
Name:         scratch-data
Description:  Scratch space for working data.
Type:         GCS_BUCKET
Stewardship:  CONTROLLED
Cloning:      COPY_RESOURCE
Access scope: SHARED_ACCESS
Managed by:   USER
GCS bucket name: scratch-data-terra-vdevel-clean-pear-3014
Location: US-CENTRAL1
# Objects: 0

ℹ️ wb resource create

Add a referenced resource

You can add a BigQuery dataset/table, GCS bucket/object, or a Git repo as a referenced resource.

wb resource add-ref

The following is an example of a BigQuery table reference creation:

wb resource add-ref bq-table --dataset-id=samples --project-id=bigquery-public-data --table-id=github_timeline --id=github_timeline
Successfully added referenced BigQuery data table.
Name:         github_timeline
Type:         BQ_TABLE
Stewardship:  REFERENCED
Cloning:      COPY_REFERENCE
GCP project id: bigquery-public-data
BigQuery dataset id: samples
BigQuery table id: github_timeline
# Rows: 6219749

ℹ️ wb resource add-ref

Locate a data resource

Use this command to list all resources in your workspace.

wb resource list

You’ll see a list of resources with their respective names, resource types, and stewardship types:

NAME                            RESOURCE TYPE         STEWARDSHIP TYPE      DESCRIPTION
1000-genomes-example-notebooks  GIT_REPO              REFERENCED            (unset)
bam-folder                      GCS_OBJECT            REFERENCED            (unset)
code                            GIT_REPO              REFERENCED            (unset)
cram-folder                     GCS_OBJECT            REFERENCED            (unset)

You can then use this command to print the underlying cloud location.

wb resource resolve --id=<resource-name>

Note: Make sure to replace <-resource-name> with the desired resource name (without brackets).

Set gcloud credentials

Use this command to set user and application default credentials that the gcloud utilities should use to access data.

gcloud auth login
gcloud auth application-default login

ℹ️ gcloud auth

Last Modified: 16 April 2024