Use the Google Workspace CLI with Arga twins

Arga provisions Google Drive, Google Docs, and Google Sheets as separate twins. Docs and Sheets each include their provider-compatible API and an interactive editor UI. When you combine these twins under one Twin Run ID, they share synchronized file state while keeping their API surfaces separate. 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 and API changes use the same run-scoped state, so an edit in Docs or Sheets is reflected in the matching Drive file.

End the twin run

arga twin-runs teardown "$RUN_ID"

Within one Twin Run ID, any two or more selected twins from google_drive, google_docs, and google_sheets share file metadata, content, permissions, revisions, creates, edits, renames, trash, and deletes. State never carries across different Twin Run IDs.

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