Author: AnVIL Team

# GCPtools

GCPtools is a package that provides an interface to Google Cloud Platform (GCP) tools, primarily the `gcloud` and `gsutil` utilities. It allows users to interact with GCP services such as Google Cloud Storage (GCS) and Google Compute Engine (GCE) directly from R.

# Installation and Load

You can install the latest version of `GCPtools` from GitHub using the following:

    if (!require("BiocManager", quietly = TRUE))
        install.packages("BiocManager")
    BiocManager::install("Bioconductor/GCPtools")

After installation, you can load the package using:

    library(GCPtools)

# `gcloud` Command Line Utility

## Check for `gcloud` SDK

The `gcloud_exists()` function is used to check if the `gcloud` command line utility is available on your system.

    gcloud_exists()
    #> [1] FALSE

## `gcloud` Help

The package provides a function to display the help for the `gcloud` command line utility. This can be useful to understand the available commands and options. They can be used in conjunction with `gcloud_cmd()` to run specific commands.

    gcloud_help() |>
        head(10L)

## Access Token

The package provides functions to interact with GCP services. For example, you can use `gcloud_access_token()` to obtain an access token for a specific service. This is currently in use by `AnVIL` and `AnVILGCP` R packages.

    gcloud_access_token("terra")

## Command Execution

You can execute `gcloud` commands using the `gcloud_cmd()` function. This function allows you to run any `gcloud` command directly from R, making it easy to interact with GCP services without leaving the R environment.

    gcloud_cmd("version")

## List of available functions

The package provides a variety of functions to interact with GCP services.

- `gcloud_exists()`: tests whether the `gcloud()` command can be found.
- `gcloud_account()`: report the current gcloud account via ⁠gcloud config get-value account⁠.
- `gcloud_project()`: report the current gcloud project via `⁠gcloud config get-value project`⁠.
- `gcloud_help()`: queries gcloud for help for a command or sub-comand via `⁠gcloud help ...`.
- `gcloud_cmd()`: `gcloud` command execution via `⁠gcloud ...`. Use pre-defined functions in preference to this.
- `gcloud_storage()`: `⁠gcloud` storage⁠ command execution via `⁠gcloud storage ...`⁠. Typically used for bucket management commands such as `rm` and `cp`.
- `gcloud_storage_buckets()`: interface to the `⁠gcloud storage buckets`⁠ command. It can create a new bucket via `⁠gcloud storage buckets create ...⁠`.

# `gsutil` Command Line Utility

## Check for `gsutil` resources

The `gsutil_exists()` function checks if a bucket or object exists in Google Cloud Storage (GCS).

    gsutil_exists("gs://your-bucket-name")

## `gsutil` Help

The `gsutil_help()` function displays the help for the `gsutil` command line utility. This can be useful to understand the available commands and options and how to use them effectively.

    gsutil_help()

The package also includes functions to manage Google Cloud Storage buckets and objects, such as `gsutil_ls()` to list objects in a bucket and `gsutil_cp()` to copy files to and from GCS.

## List of available functions

The package provides a variety of functions to interact with GCS.

- `gsutil_requesterpays()`: does the Google bucket require that the requester pay for access?
- `gsutil_requesterpays_flag()`: return the `-u <gcloud_project>` flag if the bucket requires that the requester pay for access.
- `gsutil_exists()`: check if the bucket or object exists.
- `gsutil_stat()`: print, as a side effect, the status of a bucket, directory, or file.
- `gsutil_rsync()`: synchronize a source and a destination.
- `gsutil_cat()`: concatenate bucket objects to standard output
- `gsutil_help()`: print ‘man’ page for the `gsutil` command or subcommand.
- `gsutil_pipe()`: create a pipe to read from or write to a Google bucket object.

# Disclaimer

This package is not an official Google product, nor is it affiliated with or endorsed by Google LLC. It is developed and maintained by the AnVIL team to provide a convenient interface to GCP tools for R users on the AnVIL platform.

Only the above set of `gcloud` and `gsutil` commands are supported.

# SessionInfo

    sessionInfo()
    #> R version 4.6.0 (2026-04-24)
    #> Platform: x86_64-pc-linux-gnu
    #> Running under: Ubuntu 24.04.4 LTS
    #>
    #> Matrix products: default
    #> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    #> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    #>
    #> locale:
    #>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    #>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
    #>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    #>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    #>  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    #> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    #>
    #> time zone: Etc/UTC
    #> tzcode source: system (glibc)
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] GCPtools_1.2.1   BiocStyle_2.40.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] vctrs_0.7.3          httr_1.4.8           cli_3.6.6
    #>  [4] knitr_1.51           rlang_1.2.0          xfun_0.57
    #>  [7] purrr_1.2.2          generics_0.1.4       jsonlite_2.0.0
    #> [10] glue_1.8.1           buildtools_1.0.0     htmltools_0.5.9
    #> [13] maketools_1.3.2      BiocBaseUtils_1.14.0 sys_3.4.3
    #> [16] sass_0.4.10          rappdirs_0.3.4       rmarkdown_2.31
    #> [19] tibble_3.3.1         evaluate_1.0.5       jquerylib_0.1.4
    #> [22] fastmap_1.2.0        yaml_2.3.12          lifecycle_1.0.5
    #> [25] httr2_1.2.2          BiocManager_1.30.27  compiler_4.6.0
    #> [28] dplyr_1.2.1          pkgconfig_2.0.3      tidyr_1.3.2
    #> [31] digest_0.6.39        R6_2.6.1             tidyselect_1.2.1
    #> [34] pillar_1.11.1        magrittr_2.0.5       bslib_0.11.0
    #> [37] tools_4.6.0          AnVILBase_1.6.0      cachem_1.1.0