Basic usage

Examples of typical operations performed via the Workbench CLI
Tags:
Categories:

Prior reading: Command-line interface overview

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 (command-line interface) or are working in a cloud app where it has been installed.

Start 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 wb auth login to authorize the Workbench CLI to access the relevant APIs and data with user credentials.

wb auth login

Confirm the login was successful by running wb auth status.

wb auth status
User email: xxxx@google.com
Proxy group email: PROXY_xxxxxxxxxxxxxxxxxxxxx@verily-bvdp.com
Service account email for current workspace: pet-xxxxxxxxxxxxxxxxxxxxx@terra-google-project-id-111.iam.gserviceaccount.com
LOGGED IN

Check server status

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

wb server status

List accessible workspaces

Run wb workspace list to list all workspaces that you (i.e., the logged-in user) have read or write access to.

wb workspace list

Workspaces

Create a workspace

Use wb workspace create to create a workspace.

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

The --name argument is optional; if you don't include it, the system will assign a randomly generated unique identifier (UUID).

You can use the wb status command to confirm that the workspace was created successfully.

Use an existing workspace

If you want to use an existing workspace, use the wb workspace set command.

wb workspace set --id=<workspace_id>

Delete a workspace

Run wb workspace delete to delete a workspace.

wb workspace delete --workspace=<workspace_id>

You'll see output with details of your workspace, and you'll be prompted to confirm deletion.

Data collections

Create a data collection

Data collections are based off of workspaces in Workbench. Therefore, the wb workspace create command is used to create a data collection.

wb workspace create \
  --id=<data-collection-id> \
  --pod=<pod-id> \
  --properties=terra-type=data-collection

Create a data collection version

A data collection must have at least one version. Run the wb folder create command to create a folder that will store resources for a version.

wb folder create --name=<version_name>

Rename a data collection version

Use the wb folder update command to change the name of a data collection version.

wb folder update \
  --id=<folder_uuid> \
  --new-name=<new_folder_name> \
  --move-to-root

Note that the version folder's ID won't change.

Delete a data collection

Run wb workspace delete to delete a data collection.

wb workspace delete --workspace=<data_collection_id>

You'll see output with details of your data collection, and you'll be prompted to confirm deletion.

Resources

Add a controlled resource

The wb resource create command lets you add controlled resources to GCP-backed and AWS-backed workspaces.

You can add a controlled BigQuery dataset, Cloud Storage bucket, GCP notebook, or GCP Dataproc cluster via the Workbench CLI.

Cloud Storage bucket

The following example shows the command and output of a newly created Cloud Storage bucket resource named "scratch-data":

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-google-project-id-3014
Location: US-CENTRAL1
# Objects: 0

BigQuery dataset

wb resource create bq-dataset \
  --id=<your_dataset_name>

Successfully added controlled BigQuery dataset.
ID:           <your_dataset_name>
Description:
Type:         BQ_DATASET
Stewardship:  CONTROLLED
Cloning:      COPY_RESOURCE
Access scope: SHARED_ACCESS
Managed by:   USER
Region:       us-central1
Properties:   class Properties {
    []
}
GCP project id:      vwb-google-project-id-3016
BigQuery dataset id: test_dataset_cli
Location:            us-central1
# Tables:            0

GCP Dataproc cluster

This example creates a Dataproc cluster named test-cluster-cli. You can add the optional --bucket and --temp-bucket flags and assign them to existing buckets in your workspace. If these flags aren't included in the command, default buckets named dataproc-staging-<your-workspace-name> and dataproc-temp-<your-workspace-name> will be automatically created. If your workspace already has dataproc-staging and dataproc-temp buckets, the cluster will use those buckets by default.

wb resource create dataproc-cluster \
  --id=test-cluster-cli

Creating a Dataproc cluster will also create buckets: dataproc-staging-<your-workspace-name> and dataproc-temp-<your-workspace-name>. Are you sure you want to proceed (y/N)? y
Successfully created dataproc-staging-<your-workspace-name>
Successfully created dataproc-temp-<your-workspace-name>
Successfully added controlled GCP Dataproc cluster.
ID:           test-cluster-cli
Description:
Type:         DATAPROC_CLUSTER
Stewardship:  CONTROLLED
Cloning:      COPY_NOTHING
Access scope: PRIVATE_ACCESS
Managed by:   USER
Region:       us-central1
Private user: xxx@xxx.com
Properties:   class Properties {
    [class Property {
        key: terra-application-id
        value: JupyterLab_Spark_cluster_GCP_DATAPROC_CLUSTER
    }]
}
Project Id:   google-project-id-1234
Region:       us-central1
Cluster Id:   test-cluster-cli
Status:       RUNNING
Proxy URL:    https://t4wttbbtujholckkvmckzwrkyq-dot-us-central1.dataproc.googleusercontent.com/gateway/default/jupyter/lab/
Workers:      2
Secondary Workers:  0
Autoscaling Policy: (undefined)
Metadata:
   proxy-agent-image: us-west2-docker.pkg.dev/shared-pub-buckets-94mvrf/workbench-artifacts/workbench-app-proxy-agent:ov-dev-stable
   startup-script-url: https://raw.githubusercontent.com/verily-src/workbench-app-devcontainers/master/startupscript/dataproc/startup.sh
   terra-gcp-notebook-resource-name: test-cluster-cli
   enable-guest-attributes: TRUE
   terra-cli-server: dev-stable
   software-framework: NONE
   terra-workspace-id: your-workspace-name
   terra-resource-id: 9f980b13-cb37-47b7-9646-6d79597a5615
Idle Delete Ttl:   (undefined)

For AWS-backed workspaces, you can add a controlled S3 storage folder, S3 external bucket, ECR external repository, or Aurora database.

S3 storage folder

The following command creates an S3 storage folder with an ID of test-storage-folder.

wb resource create s3-storage-folder \
    --id test-storage-folder

Successfully added controlled AWS S3 storage folder.
ID:           test-storage-folder
Description:
Type:         AWS_S3_STORAGE_FOLDER
Stewardship:  CONTROLLED
Cloning:      COPY_REFERENCE
Access scope: SHARED_ACCESS
Managed by:   USER
Region:       us-east-1
Properties:   class Properties {
    []
}
S3 Storage Folder: s3://v0-saas-dev-us-east-1-workbench/test-storage-folder-aws_test/
region:            us-east-1
# Objects:         0

S3 external bucket

Create an S3 external bucket with an ID of test-bucket with the following command:

wb resource create s3-storage-folder \
    --id test-bucket

Successfully added controlled AWS S3 storage folder.
ID:           test-bucket
Description:
Type:         AWS_S3_STORAGE_FOLDER
Stewardship:  CONTROLLED
Cloning:      COPY_REFERENCE
Access scope: SHARED_ACCESS
Managed by:   USER
Region:       us-east-1
Properties:   class Properties {
    []
}
S3 Storage Folder: s3://v0-saas-dev-us-east-1-workbench/test-bucket-aws_test/
region:            us-east-1
# Objects:         0

ECR external repository

Run the following command to create an ECR external repository with an ID of test-repository:

wb resource create ecr-external-repository \
    --id=test-repository \
    --region=<your-region> \
    --account=<your-account-id> \

Successfully added controlled AWS ECR External Repository.
ID:           test-repository
Description:
Type:         AWS_ECR_EXTERNAL_REPOSITORY
Stewardship:  CONTROLLED
Cloning:      COPY_REFERENCE
Access scope: SHARED_ACCESS
Managed by:   USER
Region:       <your-region>
Properties:   class Properties {
    []
}
Repository Name: [All repositories in account/region]
URI:             <your-account-id>.dkr.ecr.<your-region>.amazonaws.com
AWS Account:     <your-account-id>
Region:          <your-region>

Running the command without the --repository-name parameter will grant you access to all ECR repositories in the specified account and region. If you run the command with the --repository-name parameter specified, you will be granted access only to that particular repository.

wb resource create ecr-external-repository \
    --id=test-repository-2 \
    --region=<your-region> \
    --account=<your-account-id> \
    --repository-name=<your-repo-name>

Successfully added controlled AWS ECR External Repository.
ID:           test-repository-2
Description:
Type:         AWS_ECR_EXTERNAL_REPOSITORY
Stewardship:  CONTROLLED
Cloning:      COPY_REFERENCE
Access scope: SHARED_ACCESS
Managed by:   USER
Region:       <your-region>
Properties:   class Properties {
    []
}
Repository Name: <your-repo-name>
URI:             <your-account-id>.dkr.ecr.<your-region>.amazonaws.com/<your-repo-name>
AWS Account:     <your-account-id>
Region:          <your-region>

Aurora PostgreSQL database

The following command creates an Aurora database with an ID of my-database and a database ID of my_data_workspace123:

wb resource create aurora-database \
    --id my-database \
    --database-name my_data_workspace123

Successfully added controlled AWS Aurora Database.
ID:           my-database
Type:         AWS_AURORA_DATABASE
Stewardship:  CONTROLLED
Database name:        my_data_workspace123
Cluster identifier:   <your-region>-pg-16-6-20251211-01
Region:               <your-region>
RW endpoint:          cluster-abc123.<your-region>.rds.amazonaws.com
RW user:              my_data_workspace123_rw
RO endpoint:          cluster-abc123.cluster-ro.<your-region>.rds.amazonaws.com
RO user:              my_data_workspace123_ro
Port:                 5432
Engine:               aurora-postgresql
Engine version:       16.9

For detailed information on querying an Aurora database, see Query data in Aurora.

Add a referenced resource

You can create referenced resources via the wb resource add-ref command.

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

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

You can create referenced resources for S3 storage folders, external S3 buckets, and Aurora databases.

If you have at least Reader access to a source workspace with a controlled Aurora database, you can create a referenced Aurora database resource:

wb resource add-ref aurora-database \
    --id <new-reference-id> \
    --source-workspace-id <source-workspace-id> \
    --source-resource-id <source-database-id>

This will create a referenced resource in your workspace that points to the controlled resource Aurora database. Permissions will be inherited from the source workspace, and you can resolve and query the referenced database as if it were a controlled resource. See Query data in Aurora for more information.

Update a resource

You can update certain properties of a resource. See the wb resource update documentation for details for a specific resource type.

The following command updates an Aurora database's name and description:

wb resource update aurora-database \
    --id=<resource-id> \
    --new-id "<new-id>" \
    --new-description "<new-description>"

Successfully updated Aurora Database.
ID:           <new-id>
Description:  <new-description>
Type:         AWS_AURORA_DATABASE
Stewardship:  CONTROLLED
Cloning:      COPY_REFERENCE
Access scope: SHARED_ACCESS
Managed by:   USER
Region:       us-east-1
Properties:   class Properties {
    []
}
Database name:        <new_id>_<workspace_name>
Cluster identifier:   us-east-1-pg-xx-x-20251211-01
Region:               us-east-1
RW endpoint:          v0saasdevuseast1-us-east-1-pg-xx-x-20251211-01.cluster-abcdef123456.us-east-1.rds.amazonaws.com
RW user:              <new_id>_<workspace_name>_rw
RO endpoint:          v0saasdevuseast1-us-east-1-pg-xx-x-20251211-01.cluster-ro-abcdef123456.us-east-1.rds.amazonaws.com
RO user:              <new_id>_<workspace_name>_ro
Port:                 5432
Engine:               aurora-postgresql
Engine version:       16.9

Delete a resource

The wb resource delete command deletes the specified resource.

wb resource delete --id=<resource-id>

For databases, this command will delete the database, its users, and its data.

Locate a data resource

Run wb resource list 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
nb-repo                         GIT_REPO              REFERENCED            (unset)
nextflow_tests                  AI_NOTEBOOK           CONTROLLED            (unset)
nf-core-sample-data-repo        GIT_REPO              REFERENCED            (unset)
rnaseq-nf-repo                  GIT_REPO              REFERENCED            Respository containing a Nextflow RNA...
tabular_data_autodelete_aft...  BQ_DATASET            CONTROLLED            BigQuery dataset for temporary storag...
workbench-examples              GIT_REPO              REFERENCED            (unset)
ws_files                        GCS_BUCKET            CONTROLLED            Bucket for reports and provenance rec...
ws_files_autodelete_after_t...  GCS_BUCKET            CONTROLLED            Bucket for temporary storage of file ...

View details of a resource with wb resource describe and the resource's id (i.e., the name of the resource):

$ wb resource describe --id=ws_files
Name:         ws_files
Description:  Bucket for reports and provenance records.
Type:         GCS_BUCKET
Stewardship:  CONTROLLED
Cloning:      COPY_NOTHING
Access scope: SHARED_ACCESS
Managed by:   USER
Properties:   class Properties {
    []
}
GCS bucket name: terra-google-project-id-111-ws-files
Location: US-CENTRAL1
# Objects: 0

Run wb resource resolve with the resource's ID to print the underlying cloud location.

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

Cloud apps

Create an app

Use the wb app create gcp command to create a Compute Engine app. The example below shows a JupyterLab app configuration with a specific machine type, data disk size, and GPUs.

wb app create gcp \
--app-config=jupyter-lab \
--id=<instance_name> \
--machine-type=n1-highmem-16 \
--data-disk-size=800 \
--accelerator-type=nvidia-tesla-v100 \
--accelerator-core-count=1

You'll need to use the Workbench UI to create a cloud app in an AWS-backed workspace. See Set compute options for a new app for more details.

Configure autostop idle time

Use this command to update the autostop idle time for your app. The value for <autostop-time> is in seconds and must be a whole number.

wb app update gcp \
    --id=<instance-name> \
    --new-idle-timeout-seconds=<autostop-time>


wb resource update ec2 \
    --id=<ec2-id> \
    --new-metadata=idle-timeout-seconds=<autostop-time>

Utilities

You can call Google Cloud CLI commands in Workbench with wb gcloud.

Set gcloud credentials

Call wb gcloud auth login and wb gcloud auth application-default login to set user and application default credentials that the gcloud utilities should use to access data.

gcloud auth login
gcloud auth application-default login

Last Modified: 10 June 2026