Basic usage
Categories:
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.
Prerequisites
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
Optionally, check the authentication status to confirm the login was successful.
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
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
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>
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>
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
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
Description:
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
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: 12 May 2024