Use the Google Workspace CLI with Arga twins

Arga provisions Google Drive, Google Docs, and Google Sheets as independent twins. Docs and Sheets each include their provider-compatible API and an interactive editor UI. The Google Workspace CLI (gws) reads a separate Discovery document for each service, so one CLI session can use all three.

Prerequisites

Install jq, curl, and gws, then authenticate the Arga CLI:

uv tool install arga-cli
npm install -g @googleworkspace/cli
arga login

Provision the Google service twins

Provision only the services your workflow calls. This example includes Drive metadata and both editor APIs.

TWIN_JSON="$(arga twin-runs create \
  --twins google_drive,google_docs,google_sheets \
  --ttl 60 \
  --wait \
  --json)"

RUN_ID="$(printf '%s' "$TWIN_JSON" | jq -r '.run_id')"

Install each Discovery document

Create an isolated gws configuration directory and cache each provisioned service’s Discovery document.

export ARGA_DRIVE_URL="$(printf '%s' "$TWIN_JSON" \
  | jq -r '.twins.google_drive.base_url')"
export ARGA_DOCS_URL="$(printf '%s' "$TWIN_JSON" \
  | jq -r '.twins.google_docs.base_url')"
export ARGA_SHEETS_URL="$(printf '%s' "$TWIN_JSON" \
  | jq -r '.twins.google_sheets.base_url')"

export GOOGLE_WORKSPACE_CLI_TOKEN="$(printf '%s' "$TWIN_JSON" \
  | jq -r '.twins.google_drive.env_vars.GOOGLE_ACCESS_TOKEN')"

export GOOGLE_WORKSPACE_CLI_CONFIG_DIR="$(mktemp -d)"
mkdir -p "$GOOGLE_WORKSPACE_CLI_CONFIG_DIR/cache"

curl -fsSL \
  "$ARGA_DRIVE_URL/discovery/v1/apis/drive/v3/rest" \
  -o "$GOOGLE_WORKSPACE_CLI_CONFIG_DIR/cache/drive_v3.json"
curl -fsSL \
  "$ARGA_DOCS_URL/discovery/v1/apis/docs/v1/rest" \
  -o "$GOOGLE_WORKSPACE_CLI_CONFIG_DIR/cache/docs_v1.json"
curl -fsSL \
  "$ARGA_SHEETS_URL/discovery/v1/apis/sheets/v4/rest" \
  -o "$GOOGLE_WORKSPACE_CLI_CONFIG_DIR/cache/sheets_v4.json"

gws now generates its normal Drive, Docs, and Sheets commands from the three twin Discovery documents. Do not run gws auth login; the twin token provides authentication.

Access the matching preset resources

The default Drive metadata includes the same stable Docs and Sheets IDs exposed by the editor twins.

gws drive files get \
  --params '{"fileId":"google-docs-launch-notes"}'

gws docs documents get \
  --params '{"documentId":"google-docs-launch-notes"}'

gws drive files get \
  --params '{"fileId":"google-sheets-launch-plan"}'

gws sheets +read \
  --spreadsheet google-sheets-launch-plan \
  --range "Sheet1!A1:B10"

Open $ARGA_DOCS_URL or $ARGA_SHEETS_URL in your browser to inspect and edit each twin through its UI. UI edits update the same service-local state as that twin’s API.

End the twin run

arga twin-runs teardown "$RUN_ID"

The twins share preset resource IDs and a compatible access token, but they do not share mutable runtime state. A document edit changes the Docs twin only. A spreadsheet edit changes the Sheets twin only. Drive keeps its own metadata and preset content.

TWIN_JSON and GOOGLE_WORKSPACE_CLI_TOKEN contain credentials. Do not print, commit, or share them. Repeat the configuration step for each new Twin Run.

See the Google Drive, Google Docs, and Google Sheets twin references for supported API and UI behavior.

Get started

Digital twins

Tests

Setup

Integrations

Resources

Use the Google Workspace CLI with Arga twins

Prerequisites

​Prerequisites

Prerequisites