Gws Agent CLI Operations

Google Workspace CLI (gws) Agent Guidelines

When interacting with the gws CLI or any similarly designed agent-first command-line interface, human-centric patterns—such as chaining bespoke flags or scrolling through massive data outputs—are highly inefficient.

Instead, you must optimize for predictability, defense-in-depth, and strict context window management. This skill provides the mandatory invariants, edge cases, and step-by-step methodologies for executing commands safely.

1. Schema Introspection (Do Not Guess)

Do not rely on your internal training data for API documentation. Pre-trained knowledge goes stale rapidly and guessing endpoints leads to syntax errors.

Instruction: Always use the CLI's schema introspection to look up the exact method signature before attempting an API call.

• Command Pattern: gws schema <api.surface.method>
• Example 1: gws schema drive.files.list
• Example 2: gws schema sheets.spreadsheets.create
• Expected Output: A machine-readable JSON dump detailing the exact parameters, request body schemas, response types, and required OAuth scopes. Treat this as your single canonical source of truth.

2. Raw JSON Payloads Over Bespoke Flags

Avoid using flat namespaces or individual human-friendly flags (e.g., --title "My Doc"). These abstract away the true shape of the API and make nesting complex structures difficult or impossible.

Instruction: Map your inputs directly to the API schema by passing the full, nested API payload as raw JSON.

• Use the --json flag for request bodies.
• Use the --params flag for query parameters.
• Example:

  gws sheets spreadsheets create --json '{
    "properties": {
      "title": "Q1 Budget",
      "locale": "en_US",
      "timeZone": "America/Denver"
    },
    "sheets": [{
      "properties": {
        "title": "January",
        "sheetType": "GRID",
        "gridProperties": {
          "frozenRowCount": 1, 
          "frozenColumnCount": 2,
          "rowCount": 100,
          "columnCount": 10
        },
        "hidden": false
      }
    }]
  }'

3. Context Window Discipline

APIs like Google Workspace frequently return massive JSON blobs. A single unmasked email or document response can consume a massive fraction of your context window, actively degrading your reasoning capacity.

Instruction: You must explicitly restrict the data returned to you.

• Field Masks: ALWAYS use field masks to limit the API response to only the fields you strictly need for the task at hand.
  • Example: gws drive files list --params '{"fields": "files(id,name,mimeType)"}'
• NDJSON Pagination: For list operations, do not load massive top-level arrays into memory. Use NDJSON pagination to emit one JSON object per page, allowing you to stream-process the results incrementally.
  • Example: Append the --page-all flag to your listing commands.

4. Safety Rails and Mutation Invariants

Data loss caused by hallucinated parameters is a critical threat. The CLI enforces input hardening, but you must actively test your intended actions before execution.

Instruction: ALWAYS use the --dry-run flag for any mutating operations (such as create, update, or delete).

• Reasoning: This allows you to validate the request locally and "think out loud" without actually hitting the API. Review the dry-run output to ensure no hallucinated parameters exist before running the final command without the flag.