Google Workspace

Google Workspace Claude Code Skill

Prerequisites: Install the CLI

This skill drives the google-workspace-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. macOS / Linux:

   bashCopy code
   bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/google-workspace/install.sh)
   

2. Windows (PowerShell):

   powershellCopy code
   iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/google-workspace/install.ps1 | iex
   

3. Verify: google-workspace-cli --version
4. Ensure ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows) is on $PATH.

The installer downloads the google-workspace-cli and google-workspace-mcp binaries into ~/.local/bin (macOS / Linux) or %LOCALAPPDATA%\Programs\msp-skills (Windows). It does not register the skill with your agent and writes no MCP client config - see mcp-install.md for that wire-up.

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Typed commands for the Admin SDK Directory, Reports, Enterprise License Manager, Data Transfer and Reseller methods, run per client tenant. Register each client once (a service account with domain-wide delegation impersonating that client's super admin), then ask fleet questions in one command: mfa-gaps, stale-licenses, sharing-drift, posture, leavers, oauth-apps and login-alerts fan out across every tenant. offboard runs a leaver's cleanup with suspend last (backup-code invalidation fails on a suspended account) and previews before it changes anything.

When to Use This CLI

Use this CLI when an MSP needs answers across several Google Workspace client tenants at once: 2SV coverage, licence waste, external-sharing changes, risky sign-ins, third-party app access, or a per-client posture row for a QBR. It is also the safe way to offboard a leaver, suspending the account last, and gives typed access to all 163 Admin SDK, Reports, Licensing, Data Transfer and Reseller methods per tenant.

Anti-triggers

Do not use this CLI for:

• Reading or sending a user's Gmail, Drive files or Calendar events: use Google's Workspace MCP or the end-user APIs instead.
• Microsoft 365 tenants: use CIPP or a Graph-based connector instead.
• Changing Gmail forwarding, delegates or vacation responders: that is the Gmail API, which this CLI does not cover.
• Creating Google Cloud projects or service-account keys: do that in each client's Cloud console or with gcloud, then register the key with 'tenants add'.

Unique Capabilities

Cross-client security

• mfa-gaps - Every account without 2-Step Verification across all your client tenants, ranked with unenrolled admins first.

  Reach for this for any 'who lacks 2SV' question across more than one client; it already ranks admins as critical.

  bashCopy code
  google-workspace-cli mfa-gaps --all-tenants --admins-only --agent
  

• sharing-drift - Who changed Drive or Calendar settings (any setting, not only sharing) or an app's sharing settings in the Admin console, and how many files newly went external or public (up to 5 sample names per user), across clients.

  Use it for 'what changed in sharing since last review' across clients; Drive audit needs Business Standard or higher, so run Business Starter tenants with --settings-only.

  bashCopy code
  google-workspace-cli sharing-drift --all-tenants --since 7d --agent
  

• posture - One row per client: 2SV coverage, admins without 2SV, stale licences and Drive, Calendar or app-sharing setting changes, plus current sharing and 2SV policy for tenants registered with the policy scope profile.

  Start here for a fleet overview or a QBR headline, then drill in with mfa-gaps, stale-licenses or sharing-drift.

  bashCopy code
  google-workspace-cli posture --all-tenants --csv
  

• oauth-apps - Third-party apps with access to client data across every active user and tenant, ranked by scope risk; --since switches to apps newly authorized in that window.

  Use it to find risky apps across clients; on tenants above --max-users (default 1000 active users) use --since 30d, which reads the token audit log instead.

  bashCopy code
  google-workspace-cli oauth-apps --all-tenants --min-risk high --agent
  

• login-alerts - Suspicious sign-ins, accounts Google disabled, 2SV turned off, and out-of-domain mail forwarding across clients.

  Use it for the weekly 'anything bad happen to a client account' check.

  bashCopy code
  google-workspace-cli login-alerts --all-tenants --since 7d --agent
  

Licence and seat waste

• stale-licenses - Paid licences held by suspended, never-signed-in, or idle accounts, per client, ready to reclaim.

  Use it before QBRs and renewals: suspended accounts bill like active ones.

  bashCopy code
  google-workspace-cli stale-licenses --all-tenants --inactive-days 60 --agent
  

Offboarding

• offboard - Offboard a leaver with suspend last (backup-code invalidation fails on a suspended account), a read-only preview, dry-run, and a receipt per step.

  Use it for any leaver: without --yes it only previews (read scopes are enough); applying needs a tenant registered with --scopes full. Over MCP it can only preview.

  bashCopy code
  google-workspace-cli offboard jane@example.com --successor manager@example.com --ou /Departed
  

• leavers - Suspended accounts that still hold a paid licence, groups, an admin role, OAuth tokens, or have no completed Drive transfer.

  Run it weekly to catch offboards done by hand or in the Admin console.

  bashCopy code
  google-workspace-cli leavers --all-tenants --agent
  

Command Reference

Every command below is listed with its required positional arguments. Run google-workspace-cli <command> --help for flags.

activities

• google-workspace-cli activities list <applicationName> - Retrieves a list of activities for a specific customer's account and application such as the Admin console application
• google-workspace-cli activities watch <applicationName> - Start receiving notifications for account activities. For more information, see Receiving Push Notifications.

admin-channels

• google-workspace-cli admin-channels - Stop watching resources through this channel.

analytics

• google-workspace-cli analytics - Run analytics queries on locally synced data

api

• google-workspace-cli api [interface] - Browse API resource interfaces by raw name

applications

• google-workspace-cli applications get <applicationId> - Retrieves information about an application for the given application ID.
• google-workspace-cli applications list - Lists the applications available for data transfer for a customer.

asps

• google-workspace-cli asps delete <userKey> <codeId> - Deletes an ASP issued by a user.
• google-workspace-cli asps get <userKey> <codeId> - Gets information about an ASP issued by a user.
• google-workspace-cli asps list <userKey> - Lists the ASPs issued by a user.

auth

• google-workspace-cli auth logout - Clear stored credentials
• google-workspace-cli auth set-token - Save an API token to the credentials file
• google-workspace-cli auth setup - Print steps for obtaining a credential (use --launch to open the URL)
• google-workspace-cli auth status - Show authentication status

channels

• google-workspace-cli channels - Stops watching resources through this channel.

chromeosdevices

• google-workspace-cli chromeosdevices action <resourceId> - Use [BatchChangeChromeOsDeviceStatus](https://developers.google.
• google-workspace-cli chromeosdevices get <deviceId> - Retrieves a Chrome OS device's properties.
• google-workspace-cli chromeosdevices list - Retrieves a paginated list of Chrome OS devices within an account.
• google-workspace-cli chromeosdevices move-devices-to-ou - Moves or inserts multiple Chrome OS devices to an organizational unit. You can move up to 50 devices at once.
• google-workspace-cli chromeosdevices patch <deviceId> - Updates a device's updatable properties, such as annotatedUser, annotatedLocation, notes, orgUnitPath
• google-workspace-cli chromeosdevices update <deviceId> - Updates a device's updatable properties, such as annotatedUser, annotatedLocation, notes, orgUnitPath

customer

• google-workspace-cli customer devices-chromeos batch-change-status - Changes the status of a batch of ChromeOS devices.
• google-workspace-cli customer devices-chromeos count-chrome-os-devices - Counts ChromeOS devices matching the request.
• google-workspace-cli customer devices-chromeos issue-command <deviceId> - Issues a command for the device to execute.
• google-workspace-cli customer devices-chromeos-commands get <deviceId> <commandId> - Gets command data a specific command issued to the device.

customer-usage-reports

• google-workspace-cli customer-usage-reports <date> - Retrieves a report which is a collection of properties and statistics for a specific customer's account.

customers

• google-workspace-cli customers chrome-print-servers batch-create-print-servers <parent> - Creates multiple print servers.
• google-workspace-cli customers chrome-print-servers batch-delete-print-servers <parent> - Deletes multiple print servers.
• google-workspace-cli customers chrome-print-servers create <parent> - Creates a print server.
• google-workspace-cli customers chrome-print-servers delete <name> - Deletes a print server.
• google-workspace-cli customers chrome-print-servers get <name> - Returns a print server's configuration.
• google-workspace-cli customers chrome-print-servers list <parent> - Lists print server configurations.
• google-workspace-cli customers chrome-print-servers patch <name> - Updates a print server's configuration.
• google-workspace-cli customers chrome-printers batch-create-printers <parent> - Creates printers under given Organization Unit.
• google-workspace-cli customers chrome-printers batch-delete-printers <parent> - Deletes printers in batch.
• google-workspace-cli customers chrome-printers create <parent> - Creates a printer under given Organization Unit.
• google-workspace-cli customers chrome-printers delete <name> - Deletes a Printer.
• google-workspace-cli customers chrome-printers get <name> - Returns a Printer resource (printer's config).
• google-workspace-cli customers chrome-printers list <parent> - List printers configs.
• google-workspace-cli customers chrome-printers list-printer-models <parent> - Lists the supported printer models.
• google-workspace-cli customers chrome-printers patch <name> - Updates a Printer resource.
• google-workspace-cli customers get - Retrieves a customer.
• google-workspace-cli customers patch - Patches a customer.
• google-workspace-cli customers update - Updates a customer.

doctor

• google-workspace-cli doctor - Check CLI health

domain-aliases

• google-workspace-cli domain-aliases delete <domainAliasName> - Deletes a domain Alias of the customer.
• google-workspace-cli domain-aliases get <domainAliasName> - Retrieves a domain alias of the customer.
• google-workspace-cli domain-aliases insert - Inserts a domain alias of the customer.
• google-workspace-cli domain-aliases list - Lists the domain aliases of the customer.

domains

• google-workspace-cli domains delete <domainName> - Deletes a domain of the customer.
• google-workspace-cli domains get <domainName> - Retrieves a domain of the customer.
• google-workspace-cli domains insert - Inserts a domain of the customer.
• google-workspace-cli domains list - Lists the domains of the customer.

entity-usage-reports

• google-workspace-cli entity-usage-reports <entityType> <entityKey> <date> - Retrieves a report which is a collection of properties and statistics for entities used by users within the account.

export

• google-workspace-cli export <resource> [id] - Export data to JSONL or JSON for backup, migration, or analysis

feedback

• google-workspace-cli feedback list - List recent feedback entries

groups

• google-workspace-cli groups aliases delete <groupKey> <alias> - Removes an alias.
• google-workspace-cli groups aliases insert <groupKey> - Adds an alias for the group.
• google-workspace-cli groups aliases list <groupKey> - Lists all aliases for a group.
• google-workspace-cli groups delete <groupKey> - Deletes a group.
• google-workspace-cli groups get <groupKey> - Retrieves a group's properties.
• google-workspace-cli groups insert - Creates a group.
• google-workspace-cli groups list - Retrieves all groups of a domain or of a user given a userKey (paginated).
• google-workspace-cli groups patch <groupKey> - Updates a group's properties. This method supports [patch semantics](https://developers.google.
• google-workspace-cli groups update <groupKey> - Updates a group's properties.

import

• google-workspace-cli import <resource> - Import data from JSONL file via API create/upsert calls

learnings

• google-workspace-cli learnings candidates - List auto-captured improvement candidates awaiting judgment
• google-workspace-cli learnings confirm <id> - Confirm an open candidate: print its full payload, then materialize it
• google-workspace-cli learnings forget <query> - Delete learnings matching a query (use --all to wipe every rule for that query)
• google-workspace-cli learnings list - List recorded learnings from the local google-workspace-cli search_learnings table
• google-workspace-cli learnings purge - Delete settled candidate rows (expired and confirmed; --tombstones adds rejected)
• google-workspace-cli learnings reject <id> - Reject a candidate and tombstone its derivation signature
• google-workspace-cli learnings stats - Report learn-loop effectiveness metrics from the local events table

leavers

• google-workspace-cli leavers - Suspended accounts still holding a licence, groups, admin roles, OAuth tokens, or no completed transfer

license-assignments

• google-workspace-cli license-assignments delete <skuId> <userId> - Revoke a license.
• google-workspace-cli license-assignments get <skuId> <userId> - Get a specific user's license by product SKU.
• google-workspace-cli license-assignments insert <skuId> - Assign a license.
• google-workspace-cli license-assignments list-for-product - List all users assigned licenses for a specific product SKU.
• google-workspace-cli license-assignments list-for-product-and-sku <skuId> - List all users assigned licenses for a specific product SKU.
• google-workspace-cli license-assignments patch <skuId> <userId> - Reassign a user's product SKU with a different SKU in the same product. This method supports patch semantics.
• google-workspace-cli license-assignments update <skuId> <userId> - Reassign a user's product SKU with a different SKU in the same product.

login-alerts

• google-workspace-cli login-alerts - Suspicious sign-ins, accounts Google disabled, 2SV turned off, and out-of-domain forwarding across clients

members

• google-workspace-cli members delete <groupKey> <memberKey> - Removes a member from a group.
• google-workspace-cli members get <groupKey> <memberKey> - Retrieves a group member's properties.
• google-workspace-cli members has-member <groupKey> <memberKey> - Checks whether the given user is a member of the group.
• google-workspace-cli members insert <groupKey> - Adds a user to the specified group.
• google-workspace-cli members list <groupKey> - Retrieves a paginated list of all members in a group. This method times out after 60 minutes.
• google-workspace-cli members patch <groupKey> <memberKey> - Updates the membership properties of a user in the specified group.
• google-workspace-cli members update <groupKey> <memberKey> - Updates the membership of a user in the specified group.

mfa-gaps

• google-workspace-cli mfa-gaps - Users without 2-Step Verification across client tenants, admins first

mobiledevices

• google-workspace-cli mobiledevices action <resourceId> - Takes an action that affects a mobile device. For example, remotely wiping a device.
• google-workspace-cli mobiledevices delete <resourceId> - Removes a mobile device.
• google-workspace-cli mobiledevices get <resourceId> - Retrieves a mobile device's properties.
• google-workspace-cli mobiledevices list - Retrieves a paginated list of all user-owned mobile devices for an account.

oauth-apps

• google-workspace-cli oauth-apps - Third-party OAuth apps with access to client data, across every user and tenant, ranked by scope risk

offboard

• google-workspace-cli offboard <user-email> - Offboard a leaver in the right order: revoke access, remove groups, transfer data, suspend last

orgunits

• google-workspace-cli orgunits delete <orgUnitPath> - Removes an organizational unit.
• google-workspace-cli orgunits get <orgUnitPath> - Retrieves an organizational unit.
• google-workspace-cli orgunits insert - Adds an organizational unit.
• google-workspace-cli orgunits list - Retrieves a list of all organizational units for an account.
• google-workspace-cli orgunits patch <orgUnitPath> - Updates an organizational unit. This method supports [patch semantics](https://developers.google.
• google-workspace-cli orgunits update <orgUnitPath> - Updates an organizational unit.

playbook

• google-workspace-cli playbook amend - Append a note to an existing playbook (LLM-fired self-correction, silent)
• google-workspace-cli playbook list - List stored playbooks (query_family, content presence, last observed)

posture

• google-workspace-cli posture - One row per client tenant: 2SV coverage, admins without 2SV, stale licences, Drive, Calendar and app-sharing setting changes

privileges

• google-workspace-cli privileges - Retrieves a paginated list of all privileges for a customer.

profile

• google-workspace-cli profile delete <name> - Remove a profile
• google-workspace-cli profile list - List saved profiles
• google-workspace-cli profile save <name> - Save the current invocation's non-default flags as a named profile
• google-workspace-cli profile show <name> - Show a profile's values as JSON
• google-workspace-cli profile use <name> - Print the flag values a profile will apply (does not execute anything)

recall

• google-workspace-cli recall <query> - Check prior learnings for a query before running discovery (LLM-fired, pre-discovery)

reseller-customers

• google-workspace-cli reseller-customers get <customerId> - Gets a customer account.
• google-workspace-cli reseller-customers insert - Orders a new customer's account.
• google-workspace-cli reseller-customers patch <customerId> - Updates a customer account's settings. This method supports patch semantics.
• google-workspace-cli reseller-customers update <customerId> - Updates a customer account's settings.

resellernotify

• google-workspace-cli resellernotify getwatchdetails - Returns all the details of the watch corresponding to the reseller.
• google-workspace-cli resellernotify register - Registers a Reseller for receiving notifications.
• google-workspace-cli resellernotify unregister - Unregisters a Reseller for receiving notifications.

resources

• google-workspace-cli resources buildings delete <buildingId> - Deletes a building.
• google-workspace-cli resources buildings get <buildingId> - Retrieves a building.
• google-workspace-cli resources buildings insert - Inserts a building.
• google-workspace-cli resources buildings list - Retrieves a list of buildings for an account.
• google-workspace-cli resources buildings patch <buildingId> - Patches a building.
• google-workspace-cli resources buildings update <buildingId> - Updates a building.
• google-workspace-cli resources calendars delete <calendarResourceId> - Deletes a calendar resource.
• google-workspace-cli resources calendars get <calendarResourceId> - Retrieves a calendar resource.
• google-workspace-cli resources calendars insert - Inserts a calendar resource.
• google-workspace-cli resources calendars list - Retrieves a list of calendar resources for an account.
• google-workspace-cli resources calendars patch <calendarResourceId> - Patches a calendar resource.
• google-workspace-cli resources calendars update <calendarResourceId> - Updates a calendar resource.
• google-workspace-cli resources features delete <featureKey> - Deletes a feature.
• google-workspace-cli resources features get <featureKey> - Retrieves a feature.
• google-workspace-cli resources features insert - Inserts a feature.
• google-workspace-cli resources features list - Retrieves a list of features for an account.
• google-workspace-cli resources features patch <featureKey> - Patches a feature.
• google-workspace-cli resources features rename <oldName> - Renames a feature.
• google-workspace-cli resources features update <featureKey> - Updates a feature.

role-assignments

• google-workspace-cli role-assignments delete <roleAssignmentId> - Deletes a role assignment.
• google-workspace-cli role-assignments get <roleAssignmentId> - Retrieves a role assignment.
• google-workspace-cli role-assignments insert - Creates a role assignment.
• google-workspace-cli role-assignments list - Retrieves a paginated list of all roleAssignments.

roles

• google-workspace-cli roles delete <roleId> - Deletes a role.
• google-workspace-cli roles get <roleId> - Retrieves a role.
• google-workspace-cli roles insert - Creates a role.
• google-workspace-cli roles list - Retrieves a paginated list of all the roles in a domain.
• google-workspace-cli roles patch <roleId> - Patches a role.
• google-workspace-cli roles update <roleId> - Updates a role.

schemas

• google-workspace-cli schemas delete <schemaKey> - Deletes a schema.
• google-workspace-cli schemas get <schemaKey> - Retrieves a schema.
• google-workspace-cli schemas insert - Creates a schema.
• google-workspace-cli schemas list - Retrieves all schemas for a customer.
• google-workspace-cli schemas patch <schemaKey> - Patches a schema.
• google-workspace-cli schemas update <schemaKey> - Updates a schema.

search

• google-workspace-cli search <query> - Search locally synced data

sharing-drift

• google-workspace-cli sharing-drift - External-sharing changes across client tenants: Drive, Calendar and app-sharing setting changes, new external shares, public links

stale-licenses

• google-workspace-cli stale-licenses - Paid licences held by suspended, never-used, or inactive accounts across client tenants

subscriptions

• google-workspace-cli subscriptions activate <customerId> <subscriptionId> - Activates a subscription previously suspended by the reseller.
• google-workspace-cli subscriptions change-plan <customerId> <subscriptionId> - Updates a subscription plan.
• google-workspace-cli subscriptions change-renewal-settings <customerId> <subscriptionId> - Updates a user license's renewal settings. This is applicable for accounts with annual commitment plans only.
• google-workspace-cli subscriptions change-seats <customerId> <subscriptionId> - Updates a subscription's user license settings.
• google-workspace-cli subscriptions delete <customerId> <subscriptionId> - Cancels, suspends, or transfers a subscription to direct.
• google-workspace-cli subscriptions get <customerId> <subscriptionId> - Gets a specific subscription.
• google-workspace-cli subscriptions insert <customerId> - Creates or transfer a subscription.
• google-workspace-cli subscriptions list - Lists of subscriptions managed by the reseller.
• google-workspace-cli subscriptions start-paid-service <customerId> <subscriptionId> - Immediately move a 30-day free trial subscription to a paid service subscription.
• google-workspace-cli subscriptions suspend <customerId> <subscriptionId> - Suspends an active subscription.

sync

• google-workspace-cli sync - Sync API data to local SQLite for offline search and analysis

tail

• google-workspace-cli tail [resource] - Stream live changes by polling the API at regular intervals

teach

• google-workspace-cli teach - Record a query -> resource mapping for future recall (LLM-fired, silent)

teach-lookup

• google-workspace-cli teach-lookup - Install a manual entity-lookup row (kind, canonical, value)

teach-pattern

• google-workspace-cli teach-pattern - Install a manual generalization pattern (query_template, resource_template, entity_kind)

teach-playbook

• google-workspace-cli teach-playbook - Record a CLI playbook + free-text notes for a query family

tenants

• google-workspace-cli tenants add <name> - Register a client tenant (copies its service-account key into the config dir, mode 0600 on macOS/Linux)
• google-workspace-cli tenants list - List registered client tenants
• google-workspace-cli tenants remove <name> - Remove a tenant and delete its stored service-account key copy
• google-workspace-cli tenants scopes <name> - Print the Client ID and OAuth scopes to authorize in the client's Admin console
• google-workspace-cli tenants test [name] - Verify each tenant's domain-wide delegation scope by scope, and record its customer ID and domains

tokens

• google-workspace-cli tokens delete <userKey> <clientId> - Deletes all access tokens issued by a user for an application.
• google-workspace-cli tokens get <userKey> <clientId> - Gets information about an access token issued by a user.
• google-workspace-cli tokens list <userKey> - Returns the set of tokens specified user has issued to 3rd party applications.

transfers

• google-workspace-cli transfers get <dataTransferId> - Retrieves a data transfer request by its resource ID.
• google-workspace-cli transfers insert - Inserts a data transfer request. See the [Transfer parameters](https://developers.google.
• google-workspace-cli transfers list - Lists the transfers for a customer by source user, destination user, or status.

two-step-verification

• google-workspace-cli two-step-verification <userKey> - Turns off 2-Step Verification for user.

user-usage-report

• google-workspace-cli user-usage-report <date> - Retrieves a report which is a collection of properties and statistics for a set of users with the account.

users

• google-workspace-cli users aliases delete <userKey> <alias> - Removes an alias.
• google-workspace-cli users aliases insert <userKey> - Adds an alias.
• google-workspace-cli users aliases list <userKey> - Lists all aliases for a user.
• google-workspace-cli users aliases watch <userKey> - Watches for changes in users list.
• google-workspace-cli users create-guest - Create a guest user with access to a subset of Workspace capabilities.
• google-workspace-cli users delete <userKey> - Deletes a user.
• google-workspace-cli users get <userKey> - Retrieves a user.
• google-workspace-cli users insert - Creates a user.
• google-workspace-cli users list - Retrieves a paginated list of either deleted users or all users in a domain.
• google-workspace-cli users make-admin <userKey> - Makes a user a super administrator.
• google-workspace-cli users patch <userKey> - Updates a user using patch semantics.
• google-workspace-cli users photos delete <userKey> - Removes the user's photo.
• google-workspace-cli users photos get <userKey> - Retrieves the user's photo.
• google-workspace-cli users photos patch <userKey> - Adds a photo for the user. This method supports [patch semantics](https://developers.google.
• google-workspace-cli users photos update <userKey> - Adds a photo for the user.
• google-workspace-cli users sign-out <userKey> - Signs a user out of all web and device sessions and reset their sign-in cookies.
• google-workspace-cli users undelete <userKey> - Undeletes a deleted user.
• google-workspace-cli users update <userKey> - Updates a user.
• google-workspace-cli users watch - Watches for changes in users list.

verification-codes

• google-workspace-cli verification-codes generate <userKey> - Generates new backup verification codes for the user.
• google-workspace-cli verification-codes invalidate <userKey> - Invalidates the current backup verification codes for the user.
• google-workspace-cli verification-codes list <userKey> - Returns the current set of valid backup verification codes for the specified user.

version

• google-workspace-cli version - Print version

which

• google-workspace-cli which [query] - Find the command that implements a capability

workflow

• google-workspace-cli workflow archive - Sync all resources to local store for offline access and search
• google-workspace-cli workflow status - Show local archive status and sync state for all resources

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

bashCopy code
google-workspace-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Check the match before running it: for 2-Step Verification questions which can rank two-step-verification (which turns 2SV off for one user) above mfa-gaps (the read-only cross-client 2SV report). Exit code 0 means at least one match; exit code 2 means no confident match - fall back to --help or use a narrower query. --json (and other machine formats) keep that exit-2 contract and write {"matches":[]} on stdout so agents can inspect the envelope without treating a miss as success.

Recipes

Weekly 2SV sweep, admins first

bashCopy code
google-workspace-cli mfa-gaps --all-tenants --agent --select results.tenant,results.email,results.severity,results.admin_role,meta.fetch_failures

Pulls only the fields an agent needs from every client's unenrolled accounts, and keeps meta.fetch_failures so a broken tenant is not mistaken for a clean one.

Licence waste for a QBR

bashCopy code
google-workspace-cli stale-licenses --tenant acme --inactive-days 90 --csv

Named accounts holding a paid licence that nobody uses, as CSV for the deck.

What changed in sharing this week

bashCopy code
google-workspace-cli sharing-drift --all-tenants --since 7d --settings-only

Only Admin console setting changes (any Drive or Calendar setting, plus app sharing settings), old to new, with who made them.

Check suspended leavers were fully closed

bashCopy code
google-workspace-cli leavers --all-tenants --agent

Suspended accounts still holding licences, groups, admin roles, tokens or unfinished transfers.

Offboard and apply

bashCopy code
google-workspace-cli offboard jane@example.com --successor manager@example.com --ou /Departed --release-license --yes

Runs every step in order and returns a receipt per step. Licence release is skipped while the Drive transfer runs; the receipt's next field lists one license-assignments delete command per held licence, to run once transfers list shows the transfer complete. Use --json rather than --agent for offboard: --agent implies --compact, which drops each step's detail (the OU move, token and group names, and any error text).

Auth Setup

Each client tenant is a Google service account with domain-wide delegation that impersonates that client's super admin, the same model GAM uses. Register it with 'tenants add --domain --admin --key <sa.json>' (the key is copied to keys/.json in the config dir at 0600 on macOS and Linux (on Windows it inherits the folder's permissions), next to tenants.toml; both are secrets), paste the printed Client ID and scopes into that client's Admin console under Security > Access and data control > API controls > Domain-wide delegation, then run 'tenants test ' to mint one token per scope and name any missing delegation. Scope profiles (--scopes, comma-separated, raw scope names allowed): read is the default and covers every fan-out command, but two of its scopes have no read-only variant (admin.directory.user.security and apps.licensing), so it can also sign users out and change licences; full adds the offboarding writes (user, group membership, data transfer), and its admin.directory.user scope also allows every user write, including users delete and users make-admin; policy adds cloud-identity.policies.readonly for posture's policy columns (only full includes read, so register it as --scopes read,policy or full,policy; --scopes policy alone leaves the reports nothing to read); reseller is for your own partner domain only ('tenants add --reseller --scopes reseller'), is read-only (Reseller writes also need apps.order), and is never included in --all-tenants. Schemas, calendar resources, Chrome printers and most group, OU, domain, role and device writes need extra raw scopes. Change a tenant's scopes by re-running tenants add with --yes, and print them again with 'tenants scopes '. Pick a client per command with --tenant or GOOGLE_WORKSPACE_TENANT, or fan out with --all-tenants. With no tenants registered, a raw bearer token in GOOGLE_WORKSPACE_TOKEN (or 'auth set-token') acts as the single tenant "default", including for --all-tenants and offboard. The MCP server reads the same tenant registry: register tenants with the CLI first (tenants add is not exposed over MCP), pass a tenant argument per tool call, and set GOOGLE_WORKSPACE_TENANT in the MCP server's env for the raw endpoint execute tool and the sql, search and context tools, which take no tenant argument; with two or more tenants registered and none selected (a single registered client tenant is selected automatically; a --reseller tenant never is), API commands and the sql, search and analytics reads refuse rather than guess a client; GOOGLE_WORKSPACE_TOKEN is not used once tenants are registered.

Run google-workspace-cli tenants test --all-tenants to verify every client's delegation; it exits non-zero when any scope is missing. doctor exits 0 even on a rejected key unless you pass --fail-on error.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color.

Global format flags share one contract on promoted, novel, sync, and --deliver paths:

• --json - one JSON document on stdout (sync progress events go to stderr)

• --compact - keep identity/status/timestamp fields; does not change the document vs stream shape

• --csv / --plain - tabular rows (collection envelopes unwrap to the row array)

• --quiet - one identity value per row, no envelope

• Pipeable - JSON on stdout, errors on stderr

• Filterable - --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  bashCopy code
  google-workspace-cli activities list login --user-key all --agent
  

• Previewable - --dry-run shows the request without sending

• Offline-friendly - sync/search commands can use the local SQLite store when available

• Non-interactive - never prompts, every input is a flag

• Explicit confirmation - --agent does not imply --yes; pass --yes separately only after the target, arguments, and side effects are clear

• Partial fan-out - when some tenants fail, a cross-client command still prints the other tenants' results with meta.fetch_failures but exits 6. Over MCP a non-zero exit returns only the error text, so pass allow-partial-failure (CLI: --allow-partial-failure) on fan-out calls to get the partial results, then report meta.fetch_failures instead of treating missing tenants as clean.

• Explicit retries - use --idempotent only when an already-existing create should count as success, and use --ignore-missing only when a missing delete target should count as success

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

jsonCopy code
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set - piped/agent consumers and explicit-format runs get pure JSON on stdout.

Paths and state

Agents should treat the CLI's path resolver as part of the runtime contract:

• Use --home <dir> for one invocation, or set GOOGLE_WORKSPACE_HOME=<dir> to relocate all four path kinds under one root.

• Use per-kind env vars only when a specific kind must diverge: GOOGLE_WORKSPACE_CONFIG_DIR, GOOGLE_WORKSPACE_DATA_DIR, GOOGLE_WORKSPACE_STATE_DIR, GOOGLE_WORKSPACE_CACHE_DIR.

• Resolution order is per-kind env var, --home, GOOGLE_WORKSPACE_HOME, XDG (XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME), then platform defaults.

• config contains settings like config.toml and profiles. data contains credentials.toml, data.db, cookies, and auth sidecars. state contains persisted queries, jobs, and teach.log. cache contains regenerable HTTP/cache files.

• Stored secrets live in credentials.toml under the data dir; client tenant keys (keys/<name>.json) and tenants.toml live in the config dir. Existing legacy config.toml secrets are read for compatibility and leave config.toml on the first auth write.

• Run google-workspace-cli doctor --fail-on warn to surface path and credential-location warnings. agent-context exposes a schema v4 paths block for agents that need the resolved dirs.

• For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags:

  jsonCopy code
  {
    "mcpServers": {
      "google-workspace": {
        "command": "google-workspace-mcp",
        "env": {
          "GOOGLE_WORKSPACE_HOME": "/srv/google-workspace"
        }
      }
    }
  }
  

Fleet precedence: an inherited per-kind env var overrides an explicit --home for that kind. Use GOOGLE_WORKSPACE_HOME or per-kind vars as durable fleet levers, and use --home only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing GOOGLE_WORKSPACE_HOME, or doctor will not find credentials left under the former root.

Automatic learning

This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a flag_alias candidate, and a teach on a query family without a playbook auto-synthesizes a playbook_candidate from the session's journal. Your job is judgment only: recall first, act on surfaced candidates, teach the final answer, playbook amend when you observe a correction. You never record failures by hand.

Step 1: recall before any discovery

Before list/search/drill commands on a new user question, pass the question as an argv or MCP tool argument to recall --agent. Do not interpolate user-controlled text into a shell command line.

Quoted recall "<question>" breaks on an apostrophe, which is ordinary English. A quoted heredoc breaks when a body line equals the delimiter, and that delimiter is published in these docs. Write the question with a non-shell file-writing tool, then read it back as data:

bashCopy code
# Write the question verbatim with your file-writing tool (no shell involved).
# Command substitution on a file only ever yields data  -  the shell never
# parses the file's bytes as syntax.
QUERY=$(cat /path/to/question.txt)
google-workspace-cli recall "$QUERY" --agent

Prefer MCP: pass the question as the tool's query argument. "$QUERY" after a file read is argv-safe; putting the question itself in the command text is not.

The response envelope:

jsonCopy code
{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "google-workspace-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and learnings list and learnings candidates are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught.

Step 2: decision tree

Read candidates, playbook, notes, results[0], and warnings in that order:

Copy code
if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `google-workspace-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a Results[] hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps. Default to skipping mismatches; pass --debug-mismatches only when investigating cold-start surprises.

Candidate judgment details: learnings confirm <id> prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. learnings reject <id> tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; google-workspace-cli learnings candidates lists the full open set.

Graceful degradation: if learnings confirm is an unknown command, you are driving an older binary - ignore the candidates guidance and follow the rest of the protocol.

Step 3: always read warnings

• low_confidence: row exists at confidence<2. Treat as a hint, not a skip-discovery hit.
• resource_not_in_store: the local store doesn't have the resource the learning points at. The match validator couldn't classify entities - direct-fetch and re-evaluate.
• cross_alias_match (per-result): the row was taught under a different alias and matched the live query's canonical via entity_lookups (e.g., a "USA" teach satisfying a "United States" recall). Trust the resource_id.
• similar_shape_different_entity:<canonical> (top-level): a structurally matching row exists but its canonical entity differs from the live query's. Treated as cold start; the warning carries the conflicting canonical as a hint, but the row is NOT promoted into Results.
• ambiguous_alias (top-level): a single query entity resolved to multiple canonicals (e.g., "Cards" → Arizona Cardinals + St. Louis Cardinals). Surface the ambiguity from context before committing to a resource.
• candidates_present (top-level): the envelope carries a candidates section. Handle it via the candidates branch in Step 2 before anything else.
• lookup_refresh_available (top-level): an entity in the query has no lookup row yet, but synced data could provide one. Run google-workspace-cli sync to refresh entity lookups.
• Top-level no_learnings_for_query_family: the table had no rows above the Jaccard floor. Pure cold start.

Step 4: teach & after finalizing your response - always

Teaching is unconditional. After resolving a query the store could not answer, background-teach the final resource mapping - no call-count threshold, no judging whether it was "worth" learning. The teach is the anchor of the loop: it triggers playbook synthesis for a family without a playbook, and same-referent phrasings fold into one family so near-duplicate teaches do not fragment the store. Fire it after assembling your user-facing response but BEFORE emitting it, with a shell & so the call returns immediately. Pass the query the same way as recall - argv/MCP, or file-then-$QUERY. Do not splice the question into the command text:

bashCopy code
QUERY=$(cat /path/to/question.txt)
google-workspace-cli teach --query "$QUERY" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

Silent on success. Errors only land in teach.log under the resolved state dir. Teach the most specific resource - if the user asked a broad question and you walked through parent records to find the specific answer, teach the leaf id, not the parent. The CLI uses seeded entity_lookups for cross-alias resolution at recall time, so a teach under one alias (e.g., "Niners") satisfies future queries under another alias (e.g., "49ers", "San Francisco") automatically.

PII rule: teach the structural question with identifiers stripped - never include names, emails, phone numbers, account ids, or other personal identifiers in taught queries or notes. The CLI scans teach queries for obvious email/phone shapes and warns, but does not block; strip before teaching rather than relying on the warning.

Step 5: playbooks - optional flags, automatic synthesis

You do not need to decide whether a session "deserves" a playbook: a teach on a family without one auto-synthesizes a playbook_candidate from the session's journal, and the next session judges it via confirm/reject. Attach explicit playbook flags only when you already hold choreography worth recording verbatim - workarounds the CLI didn't surface (silently-dropped flags, undocumented params, pagination tricks, payload gotchas). Prefer the integrated one-call form - record the resource learning and the playbook in the same teach invocation:

bashCopy code
# Common case: record both the resource learning AND the playbook in one call.
QUERY=$(cat /path/to/question.txt)
google-workspace-cli teach \
  --query "$QUERY" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
QUERY=$(cat /path/to/question.txt)
google-workspace-cli teach-playbook \
  --query "$QUERY" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

Playbook files are JSON with steps, entity_slots, expected_tool_calls. Notes files are markdown carrying the gotchas verbatim. File-free callers (MCP-only agents) pass the same content inline: --playbook-json and --playbook-notes on the integrated teach form, --playbook-json and --notes on teach-playbook. On the integrated teach form, the playbook flags are optional - omit them entirely for a resource-only teach. On the standalone teach-playbook form, at least one of the playbook and notes flags must be set; both empty is rejected. Playbooks are keyed on the structural query family (entities stripped) so a recipe taught from one entity-shaped query applies to every other query of the same shape, with slots_resolved binding the live query's canonical at recall time.

When you DO find a playbook on a future recall, treat it as ground truth: replay the steps with slots_resolved substitutions, skip the discovery that the choreography already documents, and read notes before any step.

Step 6: playbook amend & when your debug response identifies a correction

If your debug-protocol response identifies a concrete correction the notes or playbook should know - a workaround, an undocumented endpoint shape, a stale field name, observed schema drift, an empty-payload fallback - fire playbook amend BEFORE emitting your user-facing response. Same fire-and-forget posture as teach. Pass the query and note as argv/MCP arguments, or write each with a non-shell file tool and read them back (QUERY=$(cat ...), NOTE=$(cat ...)). Do not interpolate either string into the command text:

bashCopy code
QUERY=$(cat /path/to/question.txt)
NOTE=$(cat /path/to/note.txt)
google-workspace-cli playbook amend \
  --query "$QUERY" \
  --add-note "$NOTE"
# (append shell `&` to background it)

What counts as worth amending: a behavior you OBSERVED this session that future-you would benefit from knowing. Examples worth amending:

• A workaround for a CLI surface that silently drops or misorders a flag.
• An undocumented endpoint shape (response wrapped in {meta, results}, payload nested two levels deeper than the docs claim).
• Observed schema drift (a field renamed, an index that shifted between seasons, a category label that the API now returns lower-cased).

What does NOT belong in notes:

• The year-specific or entity-specific answer to the user's question. That's the response, not a learning.
• Per-team / per-athlete / per-row data the playbook already retrieves at runtime.
• Statements that paraphrase what the existing notes already say.

The amend command appends to the family's existing notes with a timestamped marker ([amend YYYY-MM-DDTHH:MMZ]: <text>). Multiple amends accumulate; the audit trail is visible. If no playbook exists yet for the family, amend creates a notes-only one (so cold-start corrections still land).

PII discipline for amend notes

playbook amend notes are designed to potentially flow upstream as shared knowledge in future versions of the Printing Press. Keep them clean of user-identifying content so the upstream-contribution path stays open without retroactive scrubbing:

• Do NOT embed paths to user filesystems, personal API keys or tokens, user email addresses, user GitHub handles, or specific query histories tied to a single user.
• Acceptable: endpoint shapes, undocumented field names, API gotchas, observed schema drift, workarounds for CLI surfaces, generalizable pagination or retry tactics.

If a correction is only meaningful with user-specific context, it belongs in a personal note, not in the playbook amend.

Measuring the loop

google-workspace-cli learnings stats reports recall hit rate, teach-to-reuse, playbook resolution rate, and candidate confirm/reject counts from the local learn_events table. Rates are null until they have a denominator; everything stays on this machine. Use it to check whether the loop is earning its keep for this CLI.

Disabling learning

• --no-learn on a single command short-circuits both recall and the teach write path. Use for deterministic agent flows or tests that must not be affected by accumulated learnings.
• GOOGLE_WORKSPACE_NO_LEARN=true in the environment globally disables the pipeline.

Agent Feedback

When you (or the agent) notice something off about this CLI, record it:

Copy code
google-workspace-cli feedback "the --since flag is inclusive but docs say exclusive"
google-workspace-cli feedback --stdin < notes.txt
google-workspace-cli feedback list --json --limit 10

Entries are stored locally as feedback.jsonl under the resolved data dir. They are never POSTed unless GOOGLE_WORKSPACE_FEEDBACK_ENDPOINT is set AND either --send is passed or GOOGLE_WORKSPACE_FEEDBACK_AUTO_SEND=true. Default behavior is local-only.

Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.

Output Delivery

Every command accepts --deliver <sink>. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:

Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.

Named Profiles

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled or recurring agent reuses the same saved flags while providing different input each run.

Copy code
google-workspace-cli profile save briefing --json
google-workspace-cli --profile briefing activities list login --user-key all
google-workspace-cli profile list --json
google-workspace-cli profile show briefing
google-workspace-cli profile delete briefing --yes

Explicit flags always win over profile values; profile values win over defaults. agent-context lists all available profiles under available_profiles so introspecting agents discover them at runtime.

Exit Codes

Argument Parsing

Parse $ARGUMENTS:

1. Empty, help, or --help → show google-workspace-cli --help output
2. Starts with install → ends with mcp → MCP installation; otherwise → see Prerequisites above
3. Anything else → Direct Use (execute as CLI command with --agent)

MCP Server Installation

1. Install the MCP binary (run the install script from the Prerequisites section, or see mcp-install.md for per-agent wire-up).
2. Register with Claude Code:

   bashCopy code
   claude mcp add google-workspace-mcp -- google-workspace-mcp
   

3. Verify: claude mcp list

Direct Use

1. Check if installed: which google-workspace-cli If not found, offer to install (see Prerequisites at the top of this skill).
2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
3. Execute with the --agent flag (exception: run offboard with --json, because --agent output is compact and drops each step's detail):

   bashCopy code
   google-workspace-cli <command> [subcommand] [args] --agent
   

4. If ambiguous, drill into subcommand help: google-workspace-cli <command> --help.