ggsrun

Table of Contents

• ggsrun
  • Table of Contents
  • Overview
  • Features of ggsrun
  • The 5 Pillars of the v5 Architecture
    • A. Massively Parallel I/O & UI
    • B. Full Shared Drive (Omni-Drive) Support
    • C. Intelligent GAS & MIME Resolution
    • D. Robust Fault Tolerance & Auto-Retry
    • E. MCP (Model Context Protocol) Integration
  • Installation & Setup
    • 1. Install ggsrun
    • 2. Obtain Google Cloud Credentials
    • 3. Automated Authorization (OAuth2 Loopback)
    • 4. Set Up Execution Server (GAS Side)
      • Step 4.1: Bind the Server Library
      • Step 4.2: Inject the Gateway Code
      • Step 4.3: Deploy as API Executable (For exe1 & exe2)
      • Step 4.4: Deploy as Web App (For webapps)
  • Command Reference & Usage
    • Authentication & MCP
    • Massively Parallel Download
    • Massively Parallel Upload
  • Model Context Protocol (MCP) Server & LLM Integration
    • MCP Server Configuration for Antigravity CLI
    • 1. Exposed Tools
    • 2. Standardized JSON Output (TransferResult)
    • 3. AI Agent Prompt Scenarios & Expected Behaviors
  • Deep Dive: Executing Google Apps Script (exe1, exe2, webapps)
    • Mode 1: exe1 (Stateful Project Execution)
      • Architecture Workflow
    • Mode 2: exe2 (Stateless Dynamic Execution)
      • Architecture Workflow
    • Mode 3: webapps (Anonymous OR Secure Endpoint Execution)
      • Architecture Workflow
  • Advanced Configurations
    • Modifying OAuth Scopes
  • Troubleshooting
  • Licence & Author
  • Update History
    • ggsrun
    • Server

Overview

ggsrun is an enterprise-grade CLI tool and MCP (Model Context Protocol) Server designed to relentlessly orchestrate Google Drive I/O operations and execute Google Apps Script (GAS) natively from a local terminal.

With the release of v5.1.1, ggsrun transcends its origins as a mere CLI tool. Built on Go 1.26.3+, the execution engine has been entirely rewritten from legacy serial processing into a channel-based, streaming concurrent architecture. It now serves as a high-performance, fault-tolerant I/O backend fully integrated with Omni-Drive (Shared Drives) support, advanced MIME resolution, secure redirect-following Auth logic, and a native MCP Server Mode allowing LLM agents to autonomously manage your cloud infrastructure.

Features of ggsrun

1. Develops GAS using your terminal and text editor seamlessly.
2. Executes GAS directly by injecting values into your script dynamically.
3. Downloads files concurrently from Google Drive with stunning progress visualizations.
4. Uploads files concurrently to Google Drive via native Resumable upload wrappers.
5. Downloads standalone scripts and container-bound scripts flawlessly.
6. Recursively downloads all files and folders retaining absolute directory structures.
7. Uploads script files and creates projects as standalone scripts OR container-bound scripts.
8. Manages file and folder permissions across your entire Drive.
9. Searches files in Google Drive utilizing advanced search queries and Regex.
10. Supports both robust OAuth2 looping and Service Accounts natively.

The 5 Pillars of the v5 Architecture

A. Massively Parallel I/O & UI

Legacy pseudo-asynchronous processing has been eradicated. ggsrun now utilizes a channel-based worker pool built on golang.org/x/sync/errgroup to maximize network throughput on massive folder trees.

B. Full Shared Drive (Omni-Drive) Support

The v5 engine forces supportsAllDrives=true and includeItemsFromAllDrives=true across all Google Drive API permutations. Enterprise users can now execute bulk batch operations targeting deeply nested structures within organizational Shared Drives.

C. Intelligent GAS & MIME Resolution

The extraction logic dynamically categorizes Google workspace entities. Requests targeting GAS code bypass the standard Drive API and are automatically routed to the Apps Script API, securely landing as structured .json locally.

D. Robust Fault Tolerance & Auto-Retry

The v5 execution phase is strictly non-blocking. HTTP 429 (Rate Limits) and 5xx (Server Errors) trigger a mathematical exponential backoff sequence per-worker, ensuring aggressive self-healing.

E. MCP (Model Context Protocol) Integration

Running ggsrun mcp transforms the application into an autonomous JSON-RPC server via stdio. Large Language Model (LLM) agents can natively invoke internal capabilities without requiring any API keys locally.

Installation & Setup

1. Install ggsrun

Using Go

Requires Go 1.26.3 or higher. Pull and compile the latest binary natively:

$ go install github.com/tanaikech/ggsrun@latest

Downloading Pre-built Binaries

Alternatively, you can download pre-built binaries directly from the Releases page.

The following compiled binaries are available:

• macOS (Darwin)
  • ggsrun_darwin_amd64
  • ggsrun_darwin_arm64
• Linux
  • ggsrun_linux_386
  • ggsrun_linux_amd64
  • ggsrun_linux_arm64
  • ggsrun_linux_arm7
  • ggsrun_linux_mips
  • ggsrun_linux_mipsle
• FreeBSD
  • ggsrun_freebsd_amd64
  • ggsrun_freebsd_arm64
• Windows
  • ggsrun_windows_386.exe
  • ggsrun_windows_amd64.exe
  • ggsrun_windows_arm64.exe

2. Obtain Google Cloud Credentials

1. Access the Google Cloud Console.
2. Create a new Project.
3. Navigate to APIs & Services > Library. Enable both the Google Drive API and Google Apps Script API.
4. Configure the OAuth consent screen (External/Internal).
5. Navigate to Credentials > Create Credentials > OAuth client ID. Select Desktop app.
6. Download the resulting JSON file, move it to your working directory, and rigorously rename it to exactly client_secret.json.

3. Automated Authorization (OAuth2 Loopback)

With your client_secret.json in the current directory, execute:

$ ggsrun auth

ggsrun spins up a secure local loopback listener. Your default browser will launch, request authorization, and securely hand the token back to the CLI. A persistent ggsrun.cfg file is generated.

4. Set Up Execution Server (GAS Side)

To execute arbitrary GAS functions locally without permanent deployments (exe2 and webapps modes), you must establish a gateway endpoint on Google Apps Script using the ggsrunif library.

Step 4.1: Bind the Server Library

1. Navigate to the Google Apps Script Dashboard and create a New Project.
2. Click the + icon next to Libraries.
3. Input the Target Script ID: 115-19njNHlbT-NI0hMPDnVO1sdrw2tJKCAJgOTIAPbi_jq3tOo4lVRov.
4. Set the Identifier to ggsrunif and select the latest version.

Step 4.2: Inject the Gateway Code

Replace the default code in Code.gs with the following ultra-lightweight wrappers.

const doPost = (e) => ggsrunif.WebApps(e, "pass1");
const ExecutionApi = (e) => ggsrunif.ExecutionApi(e);

(Note: Change "pass1" to a secure custom password if you plan to execute webapps anonymously).

Step 4.3: Deploy as API Executable (For exe1 & exe2)

1. Click Deploy > New Deployment.
2. Choose API Executable.
3. Set Who has access strictly to Only myself.
4. Click Deploy. Copy the Script ID for the -i flag.

Step 4.4: Deploy as Web App (For webapps)

1. Click Deploy > New Deployment.
2. Choose Web app.
3. Set Execute as to Me.
4. Set Who has access to Only myself. (Note: This highly secure setting requires the ggsrun CLI to be authenticated via ggsrun auth with Drive scopes enabled. If you need to trigger the webapp anonymously from a CI/CD pipeline without a token, set access to Anyone and rely on the -p password flag).
5. Click **Depl