Skip to content
Back to search

ggsrun

High-performance Google Drive CLI and Model Context Protocol (MCP) Server for LLM/AI agents. Natively execute Google Apps Script (GAS) under a secure whitelisted runtime sandbox, automate transfers, and manage Drive infrastructure.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tanaikech--ggsrun/badge.svg)](/listings/tanaikech--ggsrun)

HTML

<a href="/listings/tanaikech--ggsrun"><img src="/api/listings/tanaikech--ggsrun/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://github.com/tanaikech/ggsrun/releases): * **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)

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

plugin.json · Manifest · 5 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://antigravity.google/schemas/v1/plugin.json",
  3. "name": "ggsrun-plugin",
  4. "description": "Antigravity CLI plugin for safe Google Apps Script development via ggsrun MCP and sandbox guardrails."
  5. }
README.md · README · 236 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ggsrun
  2. ![](help/images/fig1a.jpg)
  3. <a name="top"></a>
  4. [![Go Version](https://img.shields.io/badge/Go-1.26.4+-00ADD8?style=for-the-badge&logo=go)](https://golang.org)
  5. [![MCP Ready](https://img.shields.io/badge/MCP-Ready-8A2BE2?style=for-the-badge)](https://modelcontextprotocol.io)
  6. [![Build Status](https://img.shields.io/badge/build-passing-brightgreen?style=for-the-badge)]()
  7. [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](LICENCE)
  8. ---
  9. ## 🚀 Overview
  10. **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.
  11. 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.
  12. ---
  13. ## 🗺️ Documentation Directory Index
  14. To make onboarding, development, and advanced operations as seamless as possible, our documentation is fully modularized. Navigate directly to your area of interest:
  15. | Guide / Manual | Description | Link |
  16. | :--- | :--- | :--- |
  17. | 🚀 **Setup & Onboarding Guide** | Step-by-step instructions to configure GCP, generate OAuth2 client secrets, link Google Apps Script, and deploy gateway endpoints. | **[Setup Guide](docs/setup_guide.md)** |
  18. | 📖 **Command Reference Manual** | In-depth breakdown of all 15+ subcommands (e.g. `exe1`, `exe2`, `download`, `upload`), recipes, and Mermaid architectural diagrams. | **[Command Reference](docs/commands_reference.md)** |
  19. | 🛡️ **Security Sandbox Guide** | Explains the memory-based wrapper injection, whitelist configuration schemas (`sandbox_config.json`), and security validation scenarios. | **[Sandbox Guide](docs/sandbox_guide.md)** |
  20. | 🔄 **Stateful Execution Lifecycle** | Deep-dive explanation of the backup, sandboxing, upload, execution, and resilient rollback phases of the `exe1` command. | **[Execution Lifecycle](docs/exe1_lifecycle.md)** |
  21. | 🤖 **MCP Server Guide** | Configuration to run `ggsrun` as an autonomous tool provider in AI environments (like Claude Desktop or Antigravity), schemas, and scenarios. | **[MCP Server Guide](docs/mcp_guide.md)** |
  22. | 💻 **Interactive TUI Filer Guide** | All keyboard shortcuts, search highlighter rules, clipboard integration, and history for the split-screen Japanese PC-98 Filer Mode (`ggsrun fd`). | **[TUI Filer Guide](docs/tui_guide.md)** |
  23. | 🧪 **Local Development & Testing** | Detailed guide for configuring environment variables (`.env`), understanding CLI/TUI mock tests, and running automated test suites. | **[Development Guide](docs/development_guide.md)** |
  24. | 🔬 **Manual Integration Tests Suite** | Guided verification commands to manually test authorization, sandbox policies, tool schemas, and local file operations. | **[Manual Tests Suite](manual-tests/README.md)** |
  25. | 📚 **Detailed User Manual** | Comprehensive manual detailing all commands, advanced options, custom editor integrations (Sublime Text), and legacy parameters. | **[Detailed Manual](help/README.md)** |
  26. | 📜 **Version Update History** | Chronological record of all updates, bug fixes, features, and refactoring milestones from v1.0.0 to the latest release. | **[Update History](help/UpdateHistory.md)** |
  27. ---
  28. ## ✨ Features of ggsrun
  29. 1. **Terminal GAS Development**: Develop Google Apps Script using your favorite local text editors and terminals seamlessly.
  30. 2. **Dynamic Script Execution**: Execute GAS directly by injecting values, arguments, and payloads into your scripts dynamically.
  31. 3. **Massively Parallel Downloads**: Pull files and folders concurrently from Google Drive with stunning progress visualizations.
  32. 4. **Massively Parallel Uploads**: Push folders recursively with native Resumable upload wrappers and automated chunks handling.
  33. 5. **Flexible Project Formats**: Download standalone scripts or container-bound projects flawlessly.
  34. 6. **Recursive Folder Structuring**: Map local directories to Google Drive folders recursively, retaining absolute directory trees.
  35. 7. **Multi-Format Container Synced Uploads**: Upload script files and instantly provision standalone scripts OR container-bound scripts.
  36. 8. **Permissions Orchestration**: Inspect, list, and manage file and folder sharing permissions across your entire Drive.
  37. 9. **Advanced Metadata Search**: Query your Google Drive utilizing Google Drive API v3 query syntax and local filename Regular Expressions (Regex).
  38. 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.
  39. 11. **Security Sandboxing**: Officially integrates with the **Antigravity CLI** via an embedded in-memory security sandbox wrapper (`--sandbox`) to guard Workspace resources.
  40. 12. **Self-Healing Project Recovery**: Restore the remote GAS project to a clean initial state at any time with a single command (`ggsrun recover`).
  41. 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.
  42. ---
  43. ## 🏛️ The 5 Pillars of the v5 Architecture
  44. ### A. Massively Parallel I/O & UI
  45. 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.
  46. * *Learn more in the **[Command Reference Manual](docs/commands_reference.md#4-file-and-directory-transfers)**.*
  47. ### B. Full Shared Drive (Omni-Drive) Support
  48. 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.
  49. * *Learn more in the **[Command Reference Manual](docs/commands_reference.md#5-drive-querying-and-search)**.*
  50. ### C. Intelligent GAS & MIME Resolution
  51. 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.
  52. * *Learn more in the **[Command Reference Manual](docs/commands_reference.md#4-file-and-directory-transfers)**.*
  53. ### D. Robust Fault Tolerance & Auto-Retry
  54. 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.
  55. * *Learn more in the **[Command Reference Manual](docs/commands_reference.md#8-conflict-resolution-guide)**.*
  56. ### E. MCP (Model Context Protocol) Integration
  57. 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.
  58. * *Learn more in the **[MCP Server Manual](docs/mcp_guide.md)**.*
  59. ---
  60. ## 📦 Rapid Installation
  61. ### Method A: Build from Source (Using Go)
  62. Requires Go 1.26.4 or higher installed. Compile and install the binary natively:
  63. ```bash
  64. $ go install github.com/tanaikech/ggsrun@latest
  65. ```
  66. ### Method B: Download Pre-built Binaries
  67. Alternatively, download the pre-compiled binary matching your CPU architecture and operating system from the [Official Releases Page](https://github.com/tanaikech/ggsrun/releases):
  68. * **macOS (Darwin)**: `ggsrun_darwin_amd64` (Intel) or `ggsrun_darwin_arm64` (Apple Silicon M1/M2/M3)
  69. * **Linux**: `ggsrun_linux_amd64` (or matching ARM, 32-bit, or MIPS variants)
  70. * **Windows**: `ggsrun_windows_amd64.exe` (or 32-bit, ARM variants)
  71. ---
  72. ## 🧪 Post-Installation Verification
  73. Once you have downloaded or compiled `ggsrun`, verify that the binary is functional inside your terminal:
  74. ### 1. Verify Command Help
  75. Run the help display command to verify the binary executes and lists available options:
  76. ```bash
  77. $ ggsrun --help
  78. ```
  79. ### 2. Setup & Authentication
  80. Before running any diagnostics or script execution commands, you must configure your Google Cloud credentials and authorize the local application.
  81. Please follow the detailed, step-by-step instructions in the **[Setup & Onboarding Guide](docs/setup_guide.md)** to:
  82. 1. Obtain and load your GCP OAuth `client_secret.json` credentials.
  83. 2. Link your Google Cloud project to your Google Apps Script project.
  84. 3. Automatically deploy and secure the execution gateway.
  85. ### 3. Run Diagnostics
  86. Once you have completed the onboarding process, verify API connectivity and loopback token health by running:
  87. ```bash
  88. $ ggsrun status
  89. ```
  90. ---
  91. ## ⚡ Quick Start: Dynamic & Complex Script Execution
  92. 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:
  93. ### 1. Execute Inline or Multi-line Script Directly (`--ss`):
  94. ```bash
  95. $ ggsrun exe1 --ss "function test(e){
  96. return 'ok ' + e.key;
  97. }" -f "test" -v '{"key":"value1"}'
  98. ```
  99. ### 2. Execute Complex Multi-line Scripts via Piped Standard Input / Heredoc:
  100. Piping script payloads via standard input completely bypasses shell quotation and variable expansion limitations, supporting arbitrary comments, regular expressions, and template literals:
  101. ```bash
  102. $ cat << 'EOF' | ggsrun exe1 -f "test" -v '{"key":"value1"}'
  103. function test(e) {
  104. // Complex regular expressions, comments, and string escapes
  105. const re = /^(https?:\/\/)?([\da-z\.-]+)\.([a-z\.]{2,6})([\/\w \.-]*)*\/?$/gi;
  106. /* Multi-line comment:
  107. Special characters: $ \ ' " ` \n \t
  108. */
  109. const msg = `Processed Key: ${e.key}`;
  110. return {
  111. status: "success",
  112. result: msg,
  113. regexMatch: re.test("https://google.com")
  114. };
  115. }
  116. EOF
  117. ```
  118. ### 3. Passing Function Arguments from a File:
  119. You can pass large JSON datasets or parameter files into your function using shell file substitution `$(< filename)` or `"$(cat filename)"`:
  120. ```bash
  121. # Pass data.json directly to the function's parameter
  122. $ ggsrun exe1 --ss "function process(data){ return Object.keys(data).length; }" -f "process" -v "$(< data.json)"
  123. # Combine with Heredoc script execution and file arguments:
  124. $ cat << 'EOF' | ggsrun exe1 -f "analyze" -v "$(< payload.json)"
  125. function analyze(e) {
  126. return "Received " + e.items.length + " records from file.";
  127. }
  128. EOF
  129. ```
  130. ### 4. Passing Function Arguments from External Command Pipelines:
  131. Pass outputs from tools like `curl`, `jq`, or custom scripts dynamically into Google Apps Script:
  132. ```bash
  133. # Fetch live API payload and pass to GAS execution
  134. $ ggsrun exe1 --ss "function run(e){ return e; }" -f "run" -v "$(curl -s https://api.github.com/users/octocat)"
  135. ```
  136. ### 5. Direct Access Token Execution (CI/CD & Automated Testing):
  137. Directly pass an OAuth2 access token via `--accesstoken` or `--at` (or `-at`). This completely bypasses `ggsrun.cfg`, refresh tokens, and credentials files, making it ideal for CI/CD environments and ephemeral pipelines:
  138. ```bash
  139. # Execute GAS script using a temporary access token without any local configuration files
  140. $ ggsrun exe1 -i "SCRIPT_ID" -ss "function main() { return 'success'; }" -f "main" --at "ACCESS_TOKEN" -j
  141. # Execute Drive search with direct access token
  142. $ ggsrun searchfiles -q "name contains 'Project'" --at "ACCESS_TOKEN" -j
  143. ```
  144. *For more detailed execution recipes, sandboxing configurations, and lifecycle guides, visit the **[Command Reference Manual](docs/commands_reference.md)**.*
  145. ---
  146. ## 🤖 Antigravity CLI Integration (Plugin Installation)
  147. You can easily integrate `ggsrun` into the **Antigravity CLI** (`agy`) as a plugin. Installing this plugin automatically registers the `ggsrun` MCP server and installs the dedicated Apps Script development Agent Skill (`skills/gas-execution/SKILL.md`).
  148. ### Installation
  149. Run the following command inside your terminal:
  150. ```bash
  151. $ agy plugin install https://github.com/tanaikech/ggsrun
  152. # or
  153. $ agy plugin install https://github.com/tanaikech/ggsrun.git
  154. ```
  155. To uninstall the plugin at any time:
  156. ```bash
  157. $ agy plugin uninstall ggsrun-plugin
  158. ```
  159. ### Plugin Directory Structure
  160. The plugin is structured as follows (excluding legacy Agent Hooks, which are now natively handled by the `ggsrun` core binary):
  161. ```
  162. ggsrun/
  163. ├── plugin.json # Plugin metadata config for Antigravity CLI
  164. ├── mcp_config.json # MCP server definitions (ggsrun-mcp, workspace-developer)
  165. └── skills/
  166. └── gas-execution/
  167. └── SKILL.md # AI agent guidelines for GAS development and execution
  168. ```
  169. ---
  170. ## 💬 Q&A & Troubleshooting
  171. For general Q&A, standard Google API errors, and runtime limits, please refer to the detailed **[Legacy Q&A Guide](help/README.md#qa)**.
  172. For setup, Web App redirects, headless authentications, and 404s, please consult the **[Setup Guide Troubleshooting Section](docs/setup_guide.md#7-troubleshooting-diagnostics)**.
  173. ---
  174. ## 📄 License & Author
  175. * **License**: [MIT License](LICENCE)
  176. * **Author**: [Tanaike](https://tanaikech.github.io/about/) (Contact: tanaike@hotmail.com)
  177. *For advanced enterprise integrations, custom architectural consultations, or security audits.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.