GWS Apps Fast

Rapid Apps Script execution and management for quick automation tasks in Google Workspace.

When to Use This Command

Run this command when you need to:

• Execute an Apps Script function immediately and retrieve its return value from the terminal
• Quickly iterate on script changes with a push-and-run workflow for rapid development
• Run one-off automation tasks like bulk email sends or spreadsheet data processing

Consider alternatives when:

• You need to set up long-running scheduled automations which require proper trigger configuration
• You are building a complex add-on that needs the full Apps Script IDE debugging environment

Quick Start

Configuration

Copy
name: gws-apps-fast
type: command
category: google-workspace

Example Invocation

Copy
claude command:run gws-apps-fast --project-id "1a2b3c4d" --function "processInvoices" --params '{"month": "march"}'

Example Output

Executing function: processInvoices
  Project: Invoice Automation (1a2b3c4d)
  Parameters: {"month": "march"}

Execution started...
  Runtime: 4.2 seconds
  Status: SUCCESS

Return value:
  {
    "processed": 47,
    "skipped": 3,
    "errors": 0,
    "totalAmount": "$12,450.00"
  }

Execution log:
  [INFO] Starting invoice processing for March 2026
  [INFO] Found 50 invoices in queue
  [INFO] Processed 47 invoices successfully
  [WARN] Skipped 3 invoices: missing vendor details

Core Concepts

Fast Execution Overview

Aspect	Details
Execution Mode	Synchronous function call with real-time log streaming
Parameter Passing	JSON parameters passed directly to the Apps Script function
Return Values	Function return values displayed in terminal as formatted JSON
Timeout	Maximum execution time of 6 minutes for consumer, 30 for Workspace
Error Handling	Full stack traces and error messages surfaced in terminal output

Execution Workflow

Select Function
      |
      v
Pass Parameters (JSON)
      |
      v
Push Latest Code (optional)
      |
      v
Execute Remotely
      |
      +---> Stream Logs
      |
      v
Return Result
      |
      v
Display Output

Configuration

Parameter	Type	Default	Description
project-id	string	(required)	Apps Script project ID for the target script
function	string	(required)	Name of the function to execute
params	string	(none)	JSON string of parameters to pass to the function
push-first	boolean	false	Push local code changes before executing
stream-logs	boolean	true	Stream execution logs in real time

Best Practices

1. Keep functions idempotent - Since you may re-run functions during development, design them to be safe to execute multiple times without causing duplicate side effects.

2. Use parameter objects instead of positional args - Passing a single JSON object as the parameter makes functions flexible and self-documenting compared to relying on argument order.

3. Add logging strategically - Use Logger.log() and console.log() at key checkpoints so the streamed output tells you exactly where execution is in long-running functions.

4. Push before execute during development - Enable the push-first flag during active development so each execution runs the latest code without a separate push step.

Common Issues

1. Execution times out - Google Apps Script has a maximum execution time. Break large operations into batches and use continuation tokens to resume across multiple invocations.

2. Parameters not received by function - Ensure the function signature accepts a single parameter object and that your JSON is valid. Malformed JSON silently passes undefined.

3. Function not found error - The function must be defined in one of the project's .gs files and must not be nested inside another function. Verify the exact function name spelling and capitalization since Apps Script function names are case-sensitive.

4. Return value truncated or missing - Large return values may be truncated in the terminal output. Use --output json for full results, or log the return value inside the function and retrieve it from the execution logs instead of relying solely on the direct return.