ggsrun

🚀 Overview

ggsrun is an enterprise-grade CLI application and Model Context Protocol (MCP) Server designed to relentlessly orchestrate Google Drive I/O operations and statefully execute Google Apps Script (GAS) natively from your local terminal or via autonomous Large Language Model (LLM) agents.

Built on Go 1.26.4+, ggsrun transitions legacy single-threaded processing into a state-of-the-art, channel-based concurrent streaming architecture. It delivers maximum network throughput, native Shared Drives (Omni-Drive) support, advanced MIME resolution, resilient self-healing retries, and a native Security Sandbox to restrict Google Workspace APIs during autonomous executions.

🗺️ Documentation Directory Index

To make onboarding, development, and advanced operations as seamless as possible, our documentation is fully modularized. Navigate directly to your area of interest:

✨ Features of ggsrun

1. Terminal GAS Development: Develop Google Apps Script using your favorite local text editors and terminals seamlessly.
2. Dynamic Script Execution: Execute GAS directly by injecting values, arguments, and payloads into your scripts dynamically.
3. Massively Parallel Downloads: Pull files and folders concurrently from Google Drive with stunning progress visualizations.
4. Massively Parallel Uploads: Push folders recursively with native Resumable upload wrappers and automated chunks handling.
5. Flexible Project Formats: Download standalone scripts or container-bound projects flawlessly.
6. Recursive Folder Structuring: Map local directories to Google Drive folders recursively, retaining absolute directory trees.
7. Multi-Format Container Synced Uploads: Upload script files and instantly provision standalone scripts OR container-bound scripts.
8. Permissions Orchestration: Inspect, list, and manage file and folder sharing permissions across your entire Drive.
9. Advanced Metadata Search: Query your Google Drive utilizing Google Drive API v3 query syntax and local filename Regular Expressions (Regex).
10. Flexible Authentication: Natively supports robust browser loopback OAuth2, secure Service Accounts, and direct Access Token injection (--accesstoken / --at) for automated testing and CI/CD pipelines.
11. Security Sandboxing: Officially integrates with the Antigravity CLI via an embedded in-memory security sandbox wrapper (--sandbox) to guard Workspace resources.
12. Self-Healing Project Recovery: Restore the remote GAS project to a clean initial state at any time with a single command (ggsrun recover).
13. Enterprise & Sandbox Proxy Ready: Natively honors environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY) for robust connectivity within Gemini Managed Agents sandboxes and enterprise corporate networks.

🏛️ The 5 Pillars of the v5 Architecture

A. Massively Parallel I/O & UI

Legacy single-threaded processing has been completely replaced. ggsrun implements a channel-based worker pool built on golang.org/x/sync/errgroup to maximize network throughput on massive folder hierarchies.

• Learn more in the Command Reference Manual.

B. Full Shared Drive (Omni-Drive) Support

The v5 engine forces supportsAllDrives=true and includeItemsFromAllDrives=true across all Google Drive API permutations, allowing enterprise Shared Drives to be mapped and managed seamlessly.

• Learn more in the Command Reference Manual.

C. Intelligent GAS & MIME Resolution

The extraction logic dynamically categorizes Google Workspace entities. Downloader rules bypass the standard Drive API for GAS files, automatically routing to the Apps Script API to download scripts natively as structured JSON or packaged ZIP archives.

• Learn more in the Command Reference Manual.

D. Robust Fault Tolerance & Auto-Retry

The v5 execution and transfer phase is strictly non-blocking. Google API Rate Limits (HTTP 429) and Server Errors (5xx) trigger an exponential backoff sequence per-worker, ensuring resilient self-healing.

• Learn more in the Command Reference Manual.

E. MCP (Model Context Protocol) Integration

Running ggsrun mcp transforms the application into an autonomous JSON-RPC background server via standard I/O, allowing Large Language Model (LLM) agents to search, transfer, and execute scripts safely.

• Learn more in the MCP Server Manual.

📦 Rapid Installation

Method A: Build from Source (Using Go)

Requires Go 1.26.4 or higher installed. Compile and install the binary natively:

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

Method B: Download Pre-built Binaries

Alternatively, download the pre-compiled binary matching your CPU architecture and operating system from the Official Releases Page:

• macOS (Darwin): ggsrun_darwin_amd64 (Intel) or ggsrun_darwin_arm64 (Apple Silicon M1/M2/M3)
• Linux: ggsrun_linux_amd64 (or matching ARM, 32-bit, or MIPS variants)
• Windows: ggsrun_windows_amd64.exe (or 32-bit, ARM variants)

🧪 Post-Installation Verification

Once you have downloaded or compiled ggsrun, verify that the binary is functional inside your terminal:

1. Verify Command Help

Run the help display command to verify the binary executes and lists available options:

$ ggsrun --help

2. Setup & Authentication

Before running any diagnostics or script execution commands, you must configure your Google Cloud credentials and authorize the local application.

Please follow the detailed, step-by-step instructions in the Setup & Onboarding Guide to:

1. Obtain and load your GCP OAuth client_secret.json credentials.
2. Link your Google Cloud project to your Google Apps Script project.
3. Automatically deploy and secure the execution gateway.

3. Run Diagnostics

Once you have completed the onboarding process, verify API connectivity and loopback token health by running:

$ ggsrun status

⚡ Quick Start: Dynamic & Complex Script Execution

With v5.3.21, ggsrun seamlessly executes inline or complex multi-line Google Apps Script code directly from your terminal or scripts without escaping issues:

1. Execute Inline or Multi-line Script Directly (--ss):

$ ggsrun exe1 --ss "function test(e){
  return 'ok ' + e.key;
}" -f "test" -v '{"key":"value1"}'

2. Execute Complex Multi-line Scripts via Piped Standard Input / Heredoc:

Piping script payloads via standard input completely bypasses shell quotation and variable expansion limitations, supporting arbitrary comments, regular expressions, and template literals:

$ cat << 'EOF' | ggsrun exe1 -f "test" -v '{"key":"value1"}'
function test(e) {
  // Complex regular expressions, comments, and string escapes
  const re = /^(https?:\/\/)?([\da-z\.-]+)\.([a-z\.]{2,6})([\/\w \.-]*)*\/?$/gi;
  /* Multi-line comment:
     Special characters: $ \ ' " ` \n