{"id":28395249,"url":"https://github.com/databiosphere/terra-cli","last_synced_at":"2025-06-27T01:31:20.266Z","repository":{"id":37056951,"uuid":"317980927","full_name":"DataBiosphere/terra-cli","owner":"DataBiosphere","description":null,"archived":false,"fork":false,"pushed_at":"2023-10-19T14:59:24.000Z","size":52542,"stargazers_count":13,"open_issues_count":13,"forks_count":4,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-06-01T06:52:38.277Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataBiosphere.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-12-02T20:19:08.000Z","updated_at":"2024-12-31T15:24:23.000Z","dependencies_parsed_at":"2023-02-17T08:31:05.762Z","dependency_job_id":"6707c3aa-3d5a-4d57-8a47-5796b6c16e2c","html_url":"https://github.com/DataBiosphere/terra-cli","commit_stats":null,"previous_names":[],"tags_count":401,"template":false,"template_full_name":null,"purl":"pkg:github/DataBiosphere/terra-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataBiosphere","download_url":"https://codeload.github.com/DataBiosphere/terra-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataBiosphere%2Fterra-cli/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262172383,"owners_count":23269996,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-31T19:39:37.512Z","updated_at":"2025-06-27T01:31:20.250Z","avatar_url":"https://github.com/DataBiosphere.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# terra-cli\n\n1. [Install and run](#install-and-run)\n    * [Requirements](#requirements)\n    * [Login](#login)\n    * [Spend profile access](#spend-profile-access)\n    * [External data](#external-data)\n    * [Local tools installation](#local-tools-installation)\n2. [Troubleshooting](#troubleshooting)\n    * [Clear context](#clear-context)\n    * [Manual Install](#manual-install)\n    * [Manual Uninstall](#manual-uninstall)\n3. [Example usage](#example-usage)\n    * [Nextflow examples](#nextflow-examples)\n4. [Commands description](#commands-description)\n    * [Applications](#applications)\n    * [Authentication](#authentication)\n    * [Clusters](#clusters)\n    * [Config](#config)\n    * [Git](#git)\n    * [Groups](#groups)\n    * [gsutil](#gsutil)\n    * [Notebooks](#notebooks)\n    * [Resources](#resources)\n        * [Update A Reference resource](#update-a-reference-resource)\n        * [GCS bucket lifecycle rules](#gcs-bucket-lifecycle-rules)\n        * [GCS bucket object reference](#gcs-bucket-object-reference)\n            * [Reference to a file or folder](#reference-to-a-file-or-folder)\n            * [Reference to multiple objects under a folder](#reference-to-multiple-objects-under-a-folder)\n        * [Mounting GCS buckets \u0026 objects](#mounting-gcs-buckets--objects)\n    * [Server](#server)\n    * [Spend](#spend)\n    * [User](#user)\n    * [Workspace](#workspace)\n5. [Workspace context for applications](#workspace-context-for-applications)\n    * [Reference in a CLI command](#reference-in-a-cli-command)\n    * [Reference in file](#reference-in-file)\n    * [See all environment variables](#see-all-environment-variables)\n    * [Run unsupported tools](#run-unsupported-tools)\n    * [Configuring Credentials for AWS Resources](#configuring-credentials-for-aws-resources)\n6. [Exit codes](#exit-codes)\n\n-----\n\n## Install and run\n\nTo install the latest version:\n\n```shell\ncurl -L https://github.com/DataBiosphere/terra-cli/releases/latest/download/download-install.sh | bash \u0026\u0026 export SUPPRESS_GCLOUD_CREDS_WARNING=true\n\n# Optional: Move to somewhere in PATH\nsudo mv terra /usr/local/bin\n\n# Talk to Verily production environment (as opposed to a test environment):\nterra server set --name=verily --quiet\n```\n\nTo install a specific version, set the version as an environment variable\n\n```shell\nexport TERRA_CLI_VERSION=0.106.0\n```\n\nBy default, the CLI will be installed without support for Docker (i.e. it won't\npull the Docker image). The TERRA_CLI_DOCKER_MODE environment variable controls\nDocker support. Set it to\n\n* DOCKER_NOT_AVAILABLE (default) to skip pulling the Docker image\n* DOCKER_AVAILABLE to pull the image (requires Docker to be installed and\n  running).\n\nRe-installing will overwrite any existing installation (i.e. all JARs and\nscripts will be overwritten), but will not modify the `$PATH`. If you have added\nthe location of the Terra CLI to your `$PATH`, you will therefore need to add\nits location to your path again after each install.\n\n### Requirements\n\n1. Java 17\n2. Docker 20.10.2 (Must be running if installing in DOCKER_AVAILABLE mode)\n3. `curl`, `tar`, `gcloud` (For install only)\n\nNote: The CLI doesn't use `gcloud` directly either during installation or normal\noperation.\nHowever, `docker pull` [may use](https://cloud.google.com/container-registry/docs/quickstart#auth) `gcloud`\nunder the covers to pull the default Docker image from GCR; therefore, `gcloud`\nis required for installation.\n\n### Login\n\nNote: If you are using the CLI on a Terra cloud environment, you do not need to\nrun the commands below. You are already logged in. You can verify this by\nrunning\n\n```shell\nterra auth status\n```\n\n* To Launch an OAuth flow that creates a new tab in your browser window where\n  you will complete the login\n  ```shell\n  terra auth login\n  ```\n\n* If the machine where you're running the CLI does not have a browser available\n  to it, then use the manual login flow by setting the browser flag using. See\n  the [Authentication](#authentication) section below for more details.\n  ```shell\n  terra config set browser MANUAL\n  ```\n\n### Spend profile access\n\nIn order to spend money in Terra (e.g. by creating a workspace and resources\nwithin it), you need access to a billing account via a spend profile. Currently,\nthere is a single spend profile used by each team. An admin user can grant you\naccess. Admins,\nsee [ADMIN.md](https://github.com/DataBiosphere/terra-cli/blob/main/ADMIN.md#spend)\nfor more details.\n\nA user can be given access to multiple spend profiles, and an admin can set the\ndefault spend profile to use. Users can override the default spend profile used\nto create a workspace by using the `--spend-profile` option during workspace\ncreate. See usage under [example usage](#example-usage).\n\n### External data\n\nIn order to read data from or write data to a private external resource in\nTerra, you must grant the appropriate data access permissions to your proxy\ngroup. To view the email address of your proxy group, run `terra auth status`\n\n### Local tools installation\n\nWhen running `terra app` commands in `LOCAL_PROCESS` `app-launch` mode (the\ndefault), it's necessary to install various tools locally. The following\ninstructions are for both macOS and Linux.\n\n* `gcloud` - Make sure you have Python installed, then download the .tar.gz\n  archive file from the [installation page](https://cloud.google.\n  com/sdk/docs/install). Run `gcloud version` to verify the installation.\n    - `gcloud builds submit` has `--gcs-bucket-resource` option to specify\n      the `--gcs-source-staging-dir` and `--gcs-log-dir`\n      options as default.\n\n* `gsutil` - This command is included in\n  the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install), or available\n  separately [here](https://cloud.google.com/storage/docs/gsutil_install).\n  Verify its installation with `gsutil version`\n  (also printed as part of `gcloud version`)\n\n* `bq` - This command is included with `gcloud`. More details are available\n  [here](https://cloud.google.com/bigquery/docs/bq-command-line-tool).\n  Similarly, verify its installation with `bq version`.\n\n* `nextflow` - Install by downloading a `bash` script and running it locally.\n  Create a `nextflow` directory somewhere convenient (e.g. `$HOME/nextflow`) and\n  switch to it. Then run `curl -s https://get.nextflow.io | bash`. Finally, move\n  the `nextflow` executable script to a location on the `$PATH`: the `$PATH` by\n  running `sudo mv nextflow /usr/local/bin/`. Verify the installation\n  with `nextflow -version`.\n\n* `git` - Follow\n  these [instructions](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n  for installing Git on your platform.\n\nNow, these applications are available in `terra` by running, for\nexample, `terra gsutil ls`. When run with `terra`, environment variables are set\nbased on resources in the active workspace, and context such as the active GCP\nproject is set up automatically.\n\n-----\n\n## Troubleshooting\n\n### Clear context\n\nClear the context file and all credentials. This will require you to login and\nselect a workspace again.\n\n```shell\ncd $HOME/.terra\nrm context.json\nrm StoredCredential\n```\n\n### Manual install\n\nA Terra CLI release includes a GitHub release of the `terra-cli` repository and\na corresponding Docker image in GCR. `download-install.sh` is a convenience\nscript that downloads the latest (or specific) version of the installation\npackage, unarchives it, runs the `install.sh` script included inside, and then\ndeletes the installation package.\n\nYou can also skip the `download-install.sh` script and do the installation\nmanually.\n\n* Download the `terra-cli.tar` install package directly from the\n  [GitHub releases page.](https://github.com/DataBiosphere/terra-cli/releases)\n* Unarchive the `tar` file.\n* Run the installation script from the unarchived directory: `./install.sh`\n\n### Manual uninstall\n\nThere is not yet an uninstaller. You can clear the entire context directory,\nwhich includes the context file, all credentials, and all JARs. This will then\nrequire a re-installation (see above).\n\n```shell\nrm -R $HOME/.terra\nrm /usr/local/bin/terra\n```\n\n-----\n\n## Example usage\n\nThe commands below walk through a brief demo of the existing commands.\n\n* Fetch the user's credentials. Check the authentication status to confirm the\n  login was successful.\n  ```shell\n  terra auth login\n  terra auth status\n  ```\n\n* Ping the Terra server.\n  ```shell\n  terra server status\n  ```\n\n* Create a new Terra workspace and backing Google project, using the user's\n  default spend profile. Check the current\n  context to confirm it was created successfully.\n  ```shell\n  terra workspace create --id=\u003cmy-workspace-id\u003e\n  terra status\n  ```\n\n* Create a new Terra workspace and backing Google project, overriding the user's\n  default spend profile. User must have access to the alternate spend profile.\n  ```shell\n  terra workspace create --id=\u003cmy-workspace-id\u003e --spend-profile=\u003calt-spend-profile\u003e\n  terra status\n  ```\n\n* List all workspaces the user has read or write access to.\n  ```shell\n  terra workspace list\n  ```\n\n* If you want to use an existing Terra workspace, use the `set` command instead\n  of `create`.\n  ```shell\n  terra workspace set --id=eb0753f9-5c45-46b3-b3b4-80b4c7bea248\n  ```\n\n* Set the Gcloud user and application default credentials.\n  ```shell\n  gcloud auth login\n  gcloud auth application-default login\n  ```\n\n### Nextflow Examples\n\nRun a Nextflow hello world example (requires Docker image set and container\nrunning, or Nextflow to be installed locally. For Docker\nsupport, `export TERRA_CLI_DOCKER_MODE=DOCKER_AVAILABLE` before\ninstalling `terra`):\n\n```shell\nterra nextflow run hello\n```\n\nRun an [example Nextflow workflow](https://github.com/nextflow-io/rnaseq-nf) in\nthe context of the Terra workspace (i.e. in the workspace's backing Google\nproject). This is the same example workflow used in the\n[GCLS tutorial](https://cloud.google.com/life-sciences/docs/tutorials/nextflow).\n\n* Download the workflow code from GitHub.\n  ```shell\n  git clone https://github.com/nextflow-io/rnaseq-nf.git\n  cd rnaseq-nf\n  git checkout v2.0\n  cd ..\n  ```\n\n* Create a bucket in the workspace for Nextflow to use.\n  ```shell\n  terra resource create gcs-bucket --name=mybucket --bucket-name=mybucket\n  ```\n\n* Update the `gls` section of the `rnaseq-nf/nextflow.config` file to point to\n  the workspace project and bucket we just created.\n  ```config\n  gls {\n      params.transcriptome = 'gs://rnaseq-nf/data/ggal/transcript.fa'\n      params.reads = 'gs://rnaseq-nf/data/ggal/gut_{1,2}.fq'\n      params.multiqc = 'gs://rnaseq-nf/multiqc'\n      process.executor = 'google-lifesciences'\n      process.container = 'nextflow/rnaseq-nf:latest'\n      workDir = \"$TERRA_mybucket/scratch\"\n\n      google.region  = 'us-east1'\n      google.project = \"$GOOGLE_CLOUD_PROJECT\"\n\n      google.lifeSciences.serviceAccountEmail = \"$GOOGLE_SERVICE_ACCOUNT_EMAIL\"\n      google.lifeSciences.network = 'network'\n      google.lifeSciences.subnetwork = 'subnetwork'\n  }\n  ```\n\n* Perform a dry-run to confirm the config is set correctly.\n  ```shell\n  terra nextflow config rnaseq-nf/main.nf -profile gls\n  ```\n\n* Kick off the workflow. (This takes about 10 minutes to complete.)\n  ```shell\n  terra nextflow run rnaseq-nf/main.nf -profile gls\n  ```\n\n* To send metrics about the workflow run to a Nextflow Tower server, first\n  define an environment variable with the Tower access token. Then specify\n  the `-with-tower` flag when kicking off the workflow.\n  ```shell\n  export TOWER_ACCESS_TOKEN=*****\n  terra nextflow run hello -with-tower\n  terra nextflow run rnaseq-nf/main.nf -profile gls -with-tower\n  ```\n\n* Call the Gcloud CLI tools in the current workspace context. This means that\n  Gcloud is configured with the backing Google project and environment variables\n  are defined that contain workspace and resource properties (e.g. bucket names,\n  pet service account email).\n  ```shell\n  terra gcloud config get-value project\n  terra gsutil ls\n  terra bq version\n  ```\n\n* See the list of supported third-party tools. The CLI runs these tools in a\n  Docker image, if `app-launch` mode is `DOCKER_CONTAINER`. If the\n  `app-launch` mode is `LOCAL_PROCESS`, the CLI will assume the tools are\n  available in the current shell environment and launch them there.\n  ```shell\n  terra app list\n  ```\n\n* Print the image tag that the CLI is currently using.\n  ```shell\n  terra config get image\n  ```\n\n-----\n\n## Commands description\n\n```\nUsage: terra [COMMAND]\nTerra CLI\nCommands:\n  app        Run applications in the workspace.\n  auth       Retrieve and manage user credentials.\n  bq         Call bq in the Terra workspace.\n  config     Configure the CLI.\n  cromwell   cromwell Generate a Cromwell configuration file.\n  gcloud     Call gcloud in the Terra workspace.\n  git        Call git in the Terra workspace.\n  group      Manage groups of users.\n  gsutil     Call gsutil in the Terra workspace.\n  nextflow   Call nextflow in the Terra workspace.\n  notebook   Use GCP Notebooks in the workspace.\n  resolve    Resolve a resource to its cloud id or path.\n  resource   Manage resources in the workspace.\n  server     Connect to a Terra server.\n  spend      Manage spend profiles.\n  status     Print details about the current workspace and server.\n  user       Manage users.\n  version    Get the installed version.\n  workspace  Setup a Terra workspace.\n```\n\n* The `resolve` command is an alias for the `terra resource resolve` command.\n* The `status` command prints details about the current workspace and server.\n* The `version` command prints the installed version string.\n* The `bq`, `gcloud`, `git`, `gsutil` and `nextflow` commands call third-party\n  applications in the context of a Terra workspace and are aliases for the\n  `terra app [application]` command\n\nThe other commands are groupings of sub-commands, described in the sections\nbelow.\n\n* `app` [Applications](#applications)\n* `auth` [Authentication](#authentication)\n* `config` [Config](#config)\n* `cromwell` [Cromwell](#cromwell)\n* `git` [Git](#Git)\n* `group` [Groups](#groups)\n* `gsutil` [gsutil](#gsutil)\n* `notebook` [Notebooks](#notebooks)\n* `resource` [Resources](#resources)\n* `server` [Server](#server)\n* `spend` [Spend](#spend)\n* `user` [User](#user)\n* `workspace` [Workspace](#workspace)\n* `folder` [Folder](#folder)\n\n### Applications\n\n```\nUsage: terra app [COMMAND]\nRun applications in the workspace.\nCommands:\n  execute  [FOR DEBUG] Execute a command in the application container for the\n             Terra workspace, with no setup.\n  list     List the supported applications.\n```\n\nThe Terra CLI allows running supported third-party tools within the context of a\nworkspace. To see supported tools, run\n\n```shell\nterra app list\n```\n\nThe `app-launch` configuration property controls how tools are run: in a Docker\ncontainer, or a local child process.\n\nIf you pass `--workspace` flag, it must come immediately after the tool:\n\n```shell\n# Works\nterra bq --workspace=\u003cworkpspace-id\u003e ls\n\n# Doesn't work, --workspace is passed to bq instead of terra\nterra bq ls --workspace=\u003cworkpspace-id\u003e\n```\n\nFor creating resources such as BigQuery dataset or GCS bucket, you must create\nthrough terra rather than through tool. This is because terra configures\npermissions for you.\n\n```shell\n# Works\nterra resource create gcs-bucket --name=\u003cresource-name\u003e\n\n# Doesn't work\nterra gsutil mb gs://\u003cbucket-name\u003e\n```\n\n### Authentication\n\n```\nUsage: terra auth [COMMAND]\nRetrieve and manage user credentials.\nCommands:\n  login   Authorize the CLI to access Terra APIs and data with user credentials.\n  revoke  Revoke credentials from an account.\n  status  Print details about the currently authorized account.\n```\n\nOnly one user can be logged in at a time. To login as a different user, run\n\n```shell\nterra auth login\n```\n\nLogin uses the Google OAuth 2.0 installed\napplication [flow](https://developers.google.com/identity/protocols/oauth2/native-app).\n\nYou don't need to login again after switching workspaces. You will need to login\nagain after switching servers, because different Terra deployments may have\ndifferent OAuth flows.\n\nBy default, the CLI opens a browser window for the user to click through the\nOAuth flow. For some use cases (e.g. CloudShell, notebook VM), this is not\npractical because there is no default (or any) browser on the machine. The CLI\nhas a browser option that controls this behavior. The below command displays a\nURL, which the user can copy to a browser on a different machine (e.g. their\nlaptop), complete the login prompt, and then copy/paste the response token back\ninto a shell on the machine where they want to use the Terra CLI.\n\n```shell\n# set the browse option\n\u003e terra config set browser MANUAL\nBrowser launch mode for login is MANUAL (CHANGED).\n\n# auth flow\n\u003e terra auth login\nPlease open the following address in a browser on any machine:\n  https://accounts.google.com/o/oauth2/auth?access_type=offline\u0026approval_prompt=force\u0026client_id=[...]\nPlease enter code: *****\nLogin successful: testuser@gmail.com\n```\n\n### Clusters\n\n```\nUsage: terra cluster [COMMAND]\nUse spark clusters in the workspace.\n\nCommands:\n  start   Start a stopped Dataproc cluster within your workspace.\n  stop    Stop a started Dataproc cluster within your workspace.\n  launch  Launch a running Dataproc cluster within your workspace.\n```\n\nYou can create a Dataproc (controlled resource) with\n\n```shell\nterra resource create gcp-dataproc-cluster --name=\u003cresourcename\u003e --bucket=\u003cconfigBucket\u003e --temp-bucket=\u003ctempBucket\u003e [--workspace=\u003cid\u003e]\n```\n\n\u003e Note: You must have controlled config and temp gcs buckets created within your workspace before creating a cluster.\n\nThese `stop`, `start` and `launch` commands are provided for convenience.\n\n* [gcp-dataproc-clusters](https://cloud.google.com/dataproc/docs/concepts/overview) are supported on workspaces\n  created on cloud platform GCP. You can also stop and start the notebook using\n  the `gcloud dataproc clusters [start|stop]` commands.\n\nTo launch a component web interface, ensure that the component has been enabled during cluster creation via the `--components` flag, then run:\n\n```shell\nterra cluster launch --name=\u003ccluster-name\u003e --proxy-view=\u003ccomponent\u003e\n```\n\nThe supported components are: YARN_RESOURCE_MANAGER, MAPREDUCE_JOB_HISTORY, SPARK_HISTORY_SERVER,  HDFS_NAMENODE, YARN_APPLICATION_TIMELINE, HIVESERVER2, TEZ, JUPYTER, JUPYTERLAB, ZEPPELIN, SOLR, FLINK_HISTORY_SERVER.\n\nSee [Dataproc optional components](https://cloud.google.com/dataproc/docs/concepts/components/overview) for more details.\n\n### Config\n\n```\nUsage: terra config [COMMAND]\nConfigure the CLI.\nCommands:\n  get   Get a configuration property value.\n  list  List all configuration properties and their values.\n  set   Set a configuration property value.\n```\n\nThese commands are property getters and setters for configuring the Terra CLI.\nCurrently, the available configuration properties are:\n\n```\nOPTION                VALUE                                          DESCRIPTION                                                 \napp-launch            DOCKER_CONTAINER                               app launch mode                                             \nbrowser               AUTO                                           browser launch for login                                    \nimage                 gcr.io/terra-cli-dev/terra-cli/0.246.0:stable  docker image id                                             \nresource-limit        1000                                           max number of resources to allow per workspace              \nconsole-logging       OFF                                            logging level for printing directly to the terminal         \nfile-logging          INFO                                           logging level for writing to files/Users/ginay/.terra/logs  \nserver                broad-dev-cli-testing                          (unset)                                                     \nworkspace             (unset)                                        (unset)                                                     \nformat                TEXT                                           output format \n```\n\n### Cromwell\n\nUtility commands for using\nthe [Cromwell](https://cromwell.readthedocs.io/en/stable/) workflow engine with\nTerra.\n\n```\nUsage: terra cromwell [COMMAND]\nCommands related to Cromwell workflows.\nCommands:\n  generate-config  Generate a Cromwell configuration file (cromwell.conf) for use on a Terra workspace cloud environment.\n```\n\nTo run Cromwell in a notebook instance:\n\n* Generate the config\n    ```shell\n    terra cromwell generate-config \\\n        (--workspace-bucket-name=bucket_name | --google-bucket-name=gs://my-bucket) \\\n        [--dir=my/path]\n    ```\n\n* One of `workspace-bucket-name` or `google-bucket-name` is required to specify\n  the bucket used by Cromwell for workflow orchestration.\n    * `workspace-bucket-name` is a Terra resource name.\n    * `google-bucket-name` is a Google Cloud Storage bucket.\n      If `google-bucket-name` does not begin with the `gs://` prefix, it will be\n      automatically added.\n\n* Start the Cromwell server on `localhost:8000`, run\n    ```shell\n    java -Dconfig.file=path/to/cromwell.conf -jar cromwell/cromwell-81.jar server\n    ```\n\n* In another terminal window, run `cromshell`. Enter `localhost:8000` for\n  cromwell server.\n\n* Start workflow through cromshell:\n  e.g. `cromshell submit workflow.wdl inputs.json [options.json] [dependencies.zip]`\n\nFor more information, see https://github.com/broadinstitute/cromshell.\n\n### Git\n\n```\nUsage: terra git [COMMAND]\nCall git command in the terra workspace. Besides calling normal Git operation, this command allow cloning git-repo resources in the workspace.\nCommands:\n  all        Clone all the git-repo resources in the workspace. Usage: terra git clone --all\n  resource   Clone specified git-repo resources in the workspace. Usage: terra git clone --resource=\u003crepoResource1Name\u003e --resource=\u003crepoResource2Name\u003e\n```\n\nTo add a git repo:\n\n```shell\nterra resource add-ref git-repo --name=\u003cresource_name\u003e --repo-url=\u003crepo_url\u003e\n```\n\n### Groups\n\n```\nUsage: terra group [COMMAND]\nManage groups of users.\nCommands:\n  add-user     Add a user to a group with a given policy.\n  create       Create a new Terra group.\n  delete       Delete an existing Terra group.\n  describe     Describe the group.\n  list         List the groups to which the current user belongs.\n  list-users   List the users in a group.\n  remove-user  Remove a user from a group with a given policy.\n```\n\nTerra groups are managed by SAM. These commands are utility wrappers around the\ngroup endpoints.\n\nSay a Terra group's email is `mygroup@mydomain.com`. `name` is `mygroup`,\nnot `mygroup@mydomain.com`:\n\n```shell\nterra group list-users --name=mygroup\n```\n\nAdding a member to a Terra group implicitly adds their pet service accounts. For\nexample, say `terra-user` is added to `mygroup@mydomain.com`. When `mygroup` is\ngranted access to a resource, `terra-user` is able to access that resource from\nany of their Terra workspaces.\n\n### gsutil\n\nYou can run `terra gsutil`\nor `terra gcloud alpha storage`. `gcloud alpha storage`\nis a newer version of `gsutil`. It doesn't support everything, but what it does\nsupport [may be significantly faster](https://stackoverflow.com/collectives/google-cloud/articles/68475140/faster-cloud-storage-transfers-using-the-gcloud-command-line).\n\n### Notebooks\n\n```\nUsage: terra notebook [COMMAND]\nUse GCP Notebooks in the workspace.\nCommands:\n  start   Start a stopped Notebook instance within your workspace.\n  stop    Stop a running Notebook instance within your workspace.\n  launch  Launch a running Notebook instance within your workspace.\n```\n\nYou can create a notebook (controlled resource) with\n\n```shell\nterra resource create [notebook-type] --name=\u003cresourcename\u003e [--workspace=\u003cid\u003e]\n```\n\nThese `stop`, `start` and `launch` commands are provided for convenience.\n\n* [gcp-notebooks](https://cloud.google.\n  com/vertex-ai/docs/workbench/notebook-solution) are supported on workspaces\n  created on cloud platform GCP. You can also stop and start the notebook using\n  the\n  `gcloud notebooks instances [start|stop]` commands.\n* [sagemaker-notebooks]() are supported on workspaces created on cloud platform\n  AWS. You can also stop and start the notebook using the\n  `aws --profile=profile-name sagemaker\n  [start-notebook-instance|stop-notebook-instance]` commands.\n\n### Resources\n\n```\nUsage: terra resource [COMMAND]\nManage resources in the workspace.\nCommands:\n  add-ref, add-referenced    Add a new referenced resource.\n  check-access               Check if you have access to a referenced resource.\n  credentials                Retrieve temporary credentials to access a cloud resource.\n  create, create-controlled  Add a new controlled resource.\n  delete                     Delete a resource from the workspace.\n  describe                   Describe a resource.\n  list                       List all resources.\n  list-tree                  List all resources and folders in tree view.\n  mount                      Mounts all workspace bucket resources.\n  move                       Move resource to a folder.\n  open-console               Retrieve console link to access a cloud resource.\n  resolve                    Resolve a resource to its cloud id or path.\n  unmount                    Unmounts all workspace bucket resources.\n  update                     Update the properties of a resource.\n```\n\nA controlled resource is a cloud resource that is managed by Terra. It exists\nwithin the current workspace context. For example, a bucket within the workspace\nGoogle project. You can create these with the `create` command.\n\nA referenced resource is a cloud resource that is NOT managed by Terra. It\nexists outside the current workspace context. For example, a BigQuery dataset\nhosted outside of Terra or in another workspace. You can add these with the\n`add-ref` command. The workspace currently supports the following referenced\nresource:\n\n* `gcs-bucket`\n* `gcs-object`\n* `bq-dataset`\n* `bq-table`\n* `git-repo`\n\nThe `check-access` command lets you see whether you have access to a particular\nresource. This is useful when a different user created or added the resource and\nsubsequently shared the workspace with you. `check-access` currently always\nreturns true for `git-repo` reference type because workspace doesn't support\nauthentication to external git services yet.\n\nThe list of resources in a workspace is maintained on the Terra Workspace\nManager server.\n\n#### Update A Reference resource\n\nUser can update the name and description of a reference resource. User can also\nupdate a reference resource to another of the same type. For instance, if a user\ncreates a reference resource to Bq dataset `foo` and later on wants to point to\nBq dataset `bar` in the same project, one can use the below command to update\nthe reference. However, one is not allowed to update the reference to a\ndifferent type (e.g. update a dataset reference to a data table reference is not\nallowed).\n\n```shell\nterra resource udpate --name=\u003cfooReferenceName\u003e --new-dataset-id=bar\n```\n\n#### GCS bucket lifecycle rules\n\nGCS bucket lifecycle rules are specified by passing a JSON-formatted file path\nto the `terra resource create gcs-bucket` command. The expected JSON structure\nmatches the one used by the `gsutil lifecycle`\n[command](https://cloud.google.com/storage/docs/gsutil/commands/lifecycle). This\nstructure is a subset of the GCS\nresource [specification](https://cloud.google.com/storage/docs/json_api/v1/buckets#lifecycle).\nBelow are some example file contents for specifying a lifecycle rule.\n\n1. Change the storage class to `ARCHIVE` after 10 days.\n    ```json\n    {\n      \"rule\": [\n        {\n          \"action\": {\n            \"type\": \"SetStorageClass\",\n            \"storageClass\": \"ARCHIVE\"\n          },\n          \"condition\": {\n            \"age\": 10\n          }\n        }\n      ]\n    }\n    ```\n\n2. Delete any objects with storage class `STANDARD` that were created before\n   December 3, 2007.\n    ```json\n    {\n      \"rule\": [\n        {\n          \"action\": {\n            \"type\": \"Delete\"\n          },\n          \"condition\": {\n            \"createdBefore\": \"2007-12-03\",\n            \"matchesStorageClass\": [\n              \"STANDARD\"\n            ]\n          }\n        }\n      ]\n    }\n    ```\n\n3. Delete any objects that are more than 365 days old.\n    ```json\n    {\n      \"rule\": [\n        {\n          \"action\": {\n            \"type\": \"Delete\"\n          },\n          \"condition\": {\n            \"age\": 365\n          }\n        }\n      ]\n    }\n    ```\n\nThere is also a command shortcut for specifying this type of lifecycle rule (3).\n\n```shell\nterra resource create gcs-bucket --name=mybucket --bucket-name=mybucket --auto-delete=365\n```\n\n#### GCS bucket object reference\n\nA reference to an GCS bucket object can be created by calling\n\n```shell\nterra resource add-ref gcs-object --name=referencename --bucket-name=mybucket --object-name=myobject\n```\n\n##### Reference to a file or folder\n\nA file or folder is treated as an object in GCS bucket. By either creating a\nfolder through the cloud console UI or copying an existing folder of files to\nthe GCS bucket, a user can create a folder object. So the user can create a\nreference to the folder if they have at least `READER` access to the bucket\nand/or `READER` access to the folder. Same with a file.\n\n##### Reference to multiple objects under a folder\n\nDifferent from other referenced resource type, there is also support for\ncreating a reference to objects in the folder. For instance, a user may create\na `foo/` folder with `bar.txt` and `secret.txt` in it. If the user have at least\nREAD access to foo/ folder, they have access to anything in the foo/ folder. So\nthey can add a reference to `foo/bar.txt`, `foo/\\*` or `foo/\\*.txt`.\n\n\u003e **NOTE** Be careful to provide the correct object name when creating a\n\u003e reference. We only check if the user has READER access to the provided path,\n\u003e we **do not** check whether the object exists. This is helpful\n\u003e because when referencing to foo/\\*, it is actually not a real object! So\n\u003e a reference to `fooo/` (where object `fooo` does not exist) can be created if\n\u003e the user has `READER` access to the bucket or `foo/\\*.png` (where there is no\n\u003e png files) if they have access to the `foo/` folder.\n\n#### Mounting GCS buckets \u0026 objects\n\nUsers can mount GCS buckets and referenced folder objects locally to the user's\nhome directory in `$HOME/workspace/` by running\n\n```shell\nterra resource mount\n```\n\nUsers can specify the `--name` flag with the name of a GCS bucket or GCS object\nresource to only mount that individual resource. This flag is useful for\nremounting a resource that had failed to mount or has been moved to a different\nfolder in the workspace.\n\nBy default, controlled GCS buckets and referenced folder objects created by the\nuser will be mounted with read-write permissions while controlled buckets\ncreated by other users and referenced bucket folders will be mounted with\nread-only permissions. Users can override this default behavior by specifying\nthe `--read-only` flag.\n\n```shell\n# all mounts to be read-only\nterra resource mount --read-only\n\n# all mounts to be read-write\nterra resource mount --name=mybucket --read-only=false\n```\n\nUsers can specify the `--disable-cache` flag. This will disable file metadata\ncaching and file type caching for objects in the mounted buckets. List\noperations such as `ls` will be slower, but will reflect the most up-to-date\nstate of the bucket. This is useful when working with collaborators in a shared\nworkspace. See more details in\nthe [gcsfuse](https://github.com/GoogleCloudPlatform/gcsfuse/blob/master/docs/semantics.md#caching)\nrepository.\n\n##### Mount Failures\n\nIf a mount has failed, an empty directory will be left at mount point with the\nresource name and a suffix error string indicating the failure. Users can\nremount the bucket after resolving bucket access or bucket reference issues.\n\nUnmounting a single resource can fail if the resource has been renamed or moved\nto a different workspace folder. In this case, users can either\nrun `terra resource unmount` to unmount all mounted resources\nin `$HOME/workspace/`. Or, users can directly list out all mounted filesystems\nwith `mount` and then unmount the resource using its mount path\nwith `fusermount -u` (for linux) or `umount` for (MacOS).\n\n### Server\n\n```\nUsage: terra server [COMMAND]\nConnect to a Terra server.\nCommands:\n  list    List all available Terra servers.\n  set     Set the Terra server to connect to.\n  status  Print status and details of the Terra server context.\n```\n\nA Terra server or environment is a set of connected Terra services (e.g.\nWorkspace Manager, Data Repo, SAM).\n\nWorkspaces exist on a single server, so switching servers will change the list\nof workspaces available to you.\n\n### Spend\n\nThese commands are intended for admin users. Admins,\nsee [ADMIN.md](https://github.com/DataBiosphere/terra-cli/blob/main/ADMIN.md#spend)\nfor more details.\n\n#### User\n\nThese user management commands are intended for admin users. Admins,\nsee [ADMIN.md](https://github.com/DataBiosphere/terra-cli/blob/main/ADMIN.md#users)\nfor more details.\n\n#### ssh-key\n\n\u003e **Ensure you have the latest CLI version.** To install new CLI version, first\n[manually uninstall](#manual-uninstall) the existing CLI and then\n[install](#install-and-run) the latest CLI.\n\n`terra user ssh-key` is how Terra does source control in a notebook environment.\nIt handles the ssh key of the current user. There is one single Terra ssh key\nper user in a given server (e.g. broad-dev). With this SSH key, you can perform\nsource control in a terra-managed notebook instance using git.\n\nTo set up an ssh key, add the terra ssh key to your local machine using the\nbelow command\n\n```shell\nterra user ssh-key add\n```\n\nYou should see in the output an ssh public key starting with `ssh-rsa`. Then\ncopy the public key from the command output and add it to\nGitHub. [GitHub's instruction link](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).\n\nIf you think your key is compromised (e.g. the private key on your local machine\nis leaked to other user), you must delete the key from your GitHub account and\ngenerate a new Terra ssh key using the below command\n\n```shell\nterra user ssh-key generate\n```\n\nOnce a new key is generated, you need to associate this new key with your GitHub\naccount\nagain. [GitHub's instruction link](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).\n\n### Workspace\n\n```\nUsage: terra workspace [COMMAND]\nSetup a Terra workspace.\nCommands:\n  add-user         Add a user or group to the workspace.\n  break-glass      Grant break-glass access to a workspace user.\n  configure-aws    Generate an AWS configuration file for a workspace.\n  duplicate        Duplicate an existing workspace.\n  create           Create a new workspace.\n  delete           Delete an existing workspace.\n  delete-property  Delete the workspace properties.\n  describe         Describe the workspace.\n  list             List all workspaces the current user can access.\n  list-users       List the users of the workspace.\n  remove-user      Remove a user or group from the workspace.\n  set              Set the workspace to an existing one.\n  set-property     Set the workspace properties.\n  update           Update an existing workspace.\n```\n\nA Terra workspace created on cloud platform GCP is backed by a Google project.\nCreating/deleting a workspace also creates/deletes the project.\n\nThe `break-glass` command is intended for admin users. Admins,\nsee [ADMIN.md](https://github.com/DataBiosphere/terra-cli/blob/main/ADMIN.md#break-glass)\nfor more details.\n\n### Folder\n```\nUsage: terra folder [COMMAND]\nSetup a folder in a Terra workspace.\nComands:\n  create        create a folder\n  delete        delete a folder\n  update        update a folder's name, description, parent folder\n  set-property  set key-value properties on a folder\n  tree          print out the folders in the workspace in a tree hiearchy\n```\n-----\n\n## Workspace context for applications\n\nThe Terra CLI defines a workspace context for applications to run in. This\ncontext includes:\n\n* `GOOGLE_CLOUD_PROJECT` environment variable set to the backing google project\n  id.\n* `GOOGLE_SERVICE_ACCOUNT_EMAIL` environment variable set to the current user's\n  pet SA email in the current workspace.\n* Environment variables that are the name of the workspace resources, prefixed\n  with `TERRA_` are set to the resolved cloud identifier for those resources (\n  e.g. `mybucket` -\u003e `TERRA_mybucket` set to `gs://mybucket`). Applies to\n  referenced and controlled resources.\n\n### Reference in a CLI command\n\nTo use a workspace reference in a Terra CLI command, escape the environment\nvariable to bypass the shell substitution on the host machine.\n\nExample commands for creating a new controlled bucket resource and then\nusing `gsutil` to get its IAM bindings.\n\n```shell\n\u003e terra resource create gcs-bucket --name=mybucket --bucket_name=mybucket\nSuccessfully added controlled GCS bucket.\n\n\u003e terra gsutil iam get \\$TERRA_mybucket\nSetting the gcloud project to the workspace project\nUpdated property [core/project].  \n{\n  \"bindings\": [\n    {\n      \"members\": [\n        \"projectEditor:terra-wsm-dev-e3d8e1f5\",\n        \"projectOwner:terra-wsm-dev-e3d8e1f5\"\n      ],\n      \"role\": \"roles/storage.legacyBucketOwner\"\n    },\n    {\n      \"members\": [\n        \"projectViewer:terra-wsm-dev-e3d8e1f5\"\n      ],\n      \"role\": \"roles/storage.legacyBucketReader\"\n    }\n  ],\n  \"etag\": \"CAE=\"\n}\n```\n\n### Reference in file\n\nTo use a workspace reference in a file or config that will be read by an\napplication, do not escape the environment variable. Since this will be running\ninside the Docker container or local process, there is no need to bypass shell\nsubstitution.\n\nExample `nextflow.config` file that includes a reference to a bucket resource in\nthe workspace, the backing Google project, and the workspace pet SA email.\n\n```config\nprofiles {\n  gls {\n      params.transcriptome = 'gs://rnaseq-nf/data/ggal/transcript.fa'\n      params.reads = 'gs://rnaseq-nf/data/ggal/gut_{1,2}.fq'\n      params.multiqc = 'gs://rnaseq-nf/multiqc'\n      process.executor = 'google-lifesciences'\n      process.container = 'nextflow/rnaseq-nf:latest'\n      workDir = \"$TERRA_mybucket/scratch\"\n   \n      google.region  = 'us-east1'\n      google.project = \"$GOOGLE_CLOUD_PROJECT\"\n   \n      google.lifeSciences.serviceAccountEmail = \"$GOOGLE_SERVICE_ACCOUNT_EMAIL\"\n      google.lifeSciences.network = 'network'\n      google.lifeSciences.subnetwork = 'subnetwork'\n  }\n}\n```\n\n### See all environment variables\n\nTo see all environment variables defined in the Docker container or local\nprocess when applications are launched\n\n```shell\nterra app execute env\n```\n\nThe `terra app execute ...` command is intended for debugging. It lets you\nexecute any command in the Docker container or local process, not just the ones\nwe've officially supported (i.e. `gsutil`, `bq`, `gcloud`, `nextflow`).\n\n### Run unsupported tools\n\nTo run tools that are not yet supported by the Terra CLI, or to use local\nversions of tools, set the `app-launch` configuration property to launch a child\nprocess on the local machine instead of inside a Docker container.\n\n```shell\nterra config set app-launch LOCAL_PROCESS\n```\n\nThen call the tool with `terra app execute`. Before running the tool command,\nthe CLI defines environment variables for each workspace resource and\nconfigures `gcloud` with the workspace project. After running the tool command,\nthe CLI restores the original `gcloud` project configuration.\n\n```shell\nterra app execute dsub \\\n    --provider google-v2 \\\n    --project \\$GOOGLE_CLOUD_PROJECT \\\n    --regions us-central1 \\\n    --logging \\$TERRA_MY_BUCKET/logging/ \\\n    --output OUT=\\$TERRA_MY_BUCKET/output/out.txt \\\n    --command 'echo \"Hello World\" \u003e \"${OUT}\"' \\\n    --wait\n```\n\n(Note: The command above came from\nthe `dsub` [README](https://github.com/DataBiosphere/dsub/blob/main/README.md#getting-started-on-google-cloud)\n.)\n\n### Configuring Credentials for AWS Resources\n\nAccessing AWS Workspace resources via the AWS CLI or SDK can be configured using\nthe `terra workspace configure-aws` command. This command writes an\n[AWS configuration file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)\nwith two profiles for each AWS resource in the workspace to a file named after\nthe Workspace in `$HOME/terra/aws/`.\n\nThe output of this command is meant to be used with the\n[bash `eval` command](https://ss64.com/bash/eval.html) to set up the current\nenvironment to access resource in the current workspace by outputting a bash\ncommand to set the `AWS_CONFIG_FILE` environment variable to the newly created\nAWS configuration file. In turn this file contains two profiles for each\nresource, one named after the resource, and one suffixed with `-ro`; the former\nprovides write/read access to the resource, the latter provides read-only.\n\n#### AWS Configuration Example\n\nWorkspace has a single AWS S3 Storage folder (output truncated):\n\n```shell\n\u003e terra resource describe --name aws_folder_20230422\nName:         aws_folder_20230422\nDescription:  My First Storage Folder\nType:         AWS_S3_STORAGE_FOLDER\nRegion:       us-east-1\n...\nAWS S3 Storage Folder: s3://v0-saas-devel-us-east-1-terra/aws_folder_20230422/\n# Objects: 0\n```\n\nCall `terra workspace configure-aws` wrapped in a bash `eval` command and note\nthat environment variable `AWS_CONFIG_FILE` points at the newly written config\nfile:\n\n``` shell\n\u003e eval \"$(terra workspace configure-aws)\"\n\u003e echo $AWS_CONFIG_FILE \n/Users/jczerk/.terra/aws/verily_devel/jczerk_aws_202304131028.conf\n```\n\nNow we can use profile `aws_folder_20230422` to copy a file into our S3 Storage\nFolder:\n\n``` shell\n\u003e aws --profile=aws_folder_20230422 s3 cp /tmp/hello.txt s3://v0-saas-devel-us-east-1-terra/aws_folder_20230422/\nupload: /tmp/hello.txt to s3://v0-saas-devel-us-east-1-terra/aws_folder_20230422/hello.txt\n```\n\nAnd using read-only profile `aws_folder_20230422-ro` allows us to list this\nfile:\n\n```shell\n\u003e aws --profile=aws_folder_20230422-ro s3 ls s3://v0-saas-devel-us-east-1-terra/aws_folder_20230422/\n2023-04-22 09:53:15          0 \n2023-05-01 11:32:10         14 hello.txt\n```\n\nBut not delete it:\n\n```shell\n\u003e aws --profile=aws_folder_20230422-ro s3 rm s3://v0-saas-devel-us-east-1-terra/aws_folder_20230422/hello.txt\ndelete failed: s3://v0-saas-devel-us-east-1-terra/aws_folder_20230422/hello.txt An error occurred (AccessDenied) when calling the DeleteObject operation: Access Denied\n```\n\nSwitching back to profile `aws_folder_20230422`, delete succeeds:\n\n```shell\n\u003e aws --profile=aws_folder_20230422 s3 rm s3://v0-saas-devel-us-east-1-terra/aws_folder_20230422/hello.txt\ndelete: s3://v0-saas-devel-us-east-1-terra/aws_folder_20230422/hello.txt\n```\n\nCaching credentials using\ntool [`aws-vault`](https://github.com/99designs/aws-vault) is recommended, and\ncan be configured using options ` --cache-with-aws-vault` and\n`--aws-vault-path`.\n\n-----\n\n## Exit codes\n\nThe CLI sets the process exit code as follows.\n\n* 0 = Successful program execution\n* 1 = User-actionable error (e.g. missing parameter, workspace not defined in\n  the current context)\n* 2 = System or internal error (e.g. error making a request to a Terra service)\n* 3 = Unexpected error (e.g. null pointer exception)\n\nApp exit codes will be passed through to the caller. e.g.\nIf `gcloud --malformedOption` returns exit code `2`, then\n`terra gcloud --malformedOption` will also return exit code `2`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabiosphere%2Fterra-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatabiosphere%2Fterra-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabiosphere%2Fterra-cli/lists"}