{"id":44654933,"url":"https://github.com/shaharia-lab/gscli","last_synced_at":"2026-02-14T21:34:46.441Z","repository":{"id":322686760,"uuid":"1090504440","full_name":"shaharia-lab/gscli","owner":"shaharia-lab","description":"Google Service CLI - Command-line tool for interacting with Gmail, Calendar, and Google Drive. AI-friendly with structured output formats (JSON, table, text) for easy integration with AI tools and automation workflows.","archived":false,"fork":false,"pushed_at":"2026-02-02T13:49:34.000Z","size":87,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T01:54:38.633Z","etag":null,"topics":["ai-tools","automation","cli","gmail","golang","google-api","google-calendar","google-drive"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shaharia-lab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["shaharia-lab"]}},"created_at":"2025-11-05T18:53:26.000Z","updated_at":"2026-02-02T13:48:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shaharia-lab/gscli","commit_stats":null,"previous_names":["shaharia-lab/gscli"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/shaharia-lab/gscli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaharia-lab%2Fgscli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaharia-lab%2Fgscli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaharia-lab%2Fgscli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaharia-lab%2Fgscli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shaharia-lab","download_url":"https://codeload.github.com/shaharia-lab/gscli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaharia-lab%2Fgscli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29456336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T21:29:27.764Z","status":"ssl_error","status_checked_at":"2026-02-14T21:28:11.111Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","automation","cli","gmail","golang","google-api","google-calendar","google-drive"],"created_at":"2026-02-14T21:34:45.417Z","updated_at":"2026-02-14T21:34:46.417Z","avatar_url":"https://github.com/shaharia-lab.png","language":"TypeScript","funding_links":["https://github.com/sponsors/shaharia-lab"],"categories":[],"sub_categories":[],"readme":"# gscli - Google Service CLI\n\n\u003e **A fast CLI tool for AI agents and developers to access Gmail, Drive, and Calendar from terminal**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub](https://img.shields.io/badge/github-shaharia--lab%2Fgscli-blue)](https://github.com/shaharia-lab/gscli)\n\n## Overview\n\n`gscli` is a powerful command-line interface designed for **AI agents**, **automation tools**, and **developers** who need programmatic access to Google services. Built with TypeScript and Bun, it provides fast, read-only access to Gmail, Google Drive, and Google Calendar directly from your terminal.\n\n### Perfect For\n\n- 🤖 **AI Assistants** - Give your AI agents context from emails, documents, and calendar\n- 🔧 **Automation** - Script workflows that need Google data\n- 💻 **Developers** - Quick CLI access without switching to browser\n- 🔌 **MCP Servers** - Integrate with Model Context Protocol tools\n- 📊 **Data Analysis** - Extract Google data for processing\n\n## Features\n\n- 📧 **Gmail** - List and search emails from your inbox\n- 📁 **Google Drive** - List, search, and download files (with PDF export for Google Docs)\n- 📅 **Calendar** - View and search calendar events with flexible date ranges\n- ⚡ **Fast** - Built with Bun for blazing-fast performance\n- 🔐 **Secure** - OAuth2 authentication with automatic token refresh\n- 🎨 **Clean Output** - Beautiful, colorful terminal interface\n- 🔒 **Read-Only** - Safe by design, no write operations\n\n## Installation\n\n### Prerequisites\n\n- [Bun](https://bun.sh) installed (for development)\n- Google Cloud Project with OAuth2 credentials\n\n### Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/shaharia-lab/gscli.git\ncd gscli\n\n# Install dependencies\nbun install\n\n# Build the binary\nbun run build\n\n# Install to user directory (recommended - no sudo needed)\nmkdir -p ~/.local/bin\ncp dist/gscli ~/.local/bin/\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n\n# Or install system-wide (requires sudo for updates)\nsudo cp dist/gscli /usr/local/bin/\n```\n\n### Pre-built Binaries\n\nDownload pre-built binaries from [GitHub Releases](https://github.com/shaharia-lab/gscli/releases):\n\n```bash\n# Linux (user directory - recommended)\ncurl -L https://github.com/shaharia-lab/gscli/releases/latest/download/gscli-linux -o gscli\nchmod +x gscli\nmkdir -p ~/.local/bin\nmv gscli ~/.local/bin/\nexport PATH=\"$HOME/.local/bin:$PATH\"\n\n# Or Linux (system-wide)\ncurl -L https://github.com/shaharia-lab/gscli/releases/latest/download/gscli-linux -o gscli\nchmod +x gscli\nsudo mv gscli /usr/local/bin/\n\n# macOS\ncurl -L https://github.com/shaharia-lab/gscli/releases/latest/download/gscli-macos -o gscli\nchmod +x gscli\nmv gscli ~/.local/bin/  # or: sudo mv gscli /usr/local/bin/\n\n# Windows\n# Download gscli-windows.exe and add to PATH\n```\n\n## Setup\n\n### 1. Get Google OAuth2 Credentials\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com)\n2. Create a new project\n3. Enable these APIs:\n   - Gmail API\n   - Google Drive API  \n   - Google Calendar API\n4. Go to **Credentials** → **Create Credentials** → **OAuth 2.0 Client ID**\n5. Select **Desktop app** as application type\n6. Download the JSON file or copy the credentials\n\n### 2. Authenticate (One-Time Setup)\n\n**Recommended: Use --client flag** (saves credentials permanently)\n\n```bash\n# Download client.json from Google Cloud Console first\n\n# Authenticate and save client credentials\ngscli auth login --client /path/to/client.json\n\n# ✅ Client credentials are now saved!\n# ✅ You can delete client.json if desired\n# ✅ All future commands work without any setup!\n```\n\n**Alternative Methods:**\n\n**Option A: Local File**\n```bash\n# Save as ./client.json in current directory\ngscli auth login\n```\n\n**Option B: Environment Variable**\n```bash\nexport GOOGLE_CLIENT_CREDENTIAL_FILE=\"/path/to/client.json\"\ngscli auth login\n```\n\nThis opens your browser for Google OAuth2 authentication. Credentials are stored securely in `~/.config/gscli/credentials.json`.\n\n## Usage\n\n### Authentication\n\n```bash\n# Login (first time)\ngscli auth login\n\n# Check authentication status\ngscli auth status\n\n# Logout\ngscli auth logout\n```\n\n### Self-Update\n\n```bash\n# Update to the latest version\ngscli update\n\n# Check for available updates\ngscli update check\n```\n\n#### Recommended Installation for Easy Updates\n\nFor the best update experience, install `gscli` in a user directory:\n\n```bash\n# Create user bin directory\nmkdir -p ~/.local/bin\n\n# Copy gscli there\ncp /path/to/gscli ~/.local/bin/\n\n# Add to your PATH (add to ~/.bashrc or ~/.zshrc)\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n\n# Now update without sudo\ngscli update\n```\n\n**Why?**\n- ✅ No sudo required for updates\n- ✅ User-owned directory\n- ✅ Clean and simple updates\n- ✅ No system-wide changes needed\n\n**If installed in `/usr/local/bin/` (requires sudo):**\n```bash\nsudo gscli update\n```\n\n### Gmail Commands\n\n```bash\n# List recent emails (default: 10)\ngscli gmail list\n\n# List with custom limit\ngscli gmail list --limit 20\n\n# List from specific folder/label\ngscli gmail list --folder SENT\n\n# Search emails with Gmail query syntax\ngscli gmail search \"from:boss@example.com subject:report\"\ngscli gmail search \"is:unread after:2025/11/01\"\n\n# Read a specific email by ID\ngscli gmail read \u003cmessage-id\u003e\n\n# List all folders/labels\ngscli gmail folders-list\n```\n\n### Google Drive Commands\n\n```bash\n# List files in root directory\ngscli drive list\n\n# List files including shared with you\ngscli drive list --include-shared\n\n# List files in specific folder\ngscli drive list --folder \"Project Docs\"\n\n# Search for files by name\ngscli drive search \"Budget 2025\"\n\n# Download a file\ngscli drive download \u003cfile-id\u003e\n\n# Export Google Docs to different formats\ngscli drive download \u003cdoc-id\u003e --format pdf        # PDF (default)\ngscli drive download \u003cdoc-id\u003e --format markdown   # Markdown\ngscli drive download \u003cdoc-id\u003e --format txt        # Plain text\ngscli drive download \u003cdoc-id\u003e --format docx       # Microsoft Word\n\n# Export Google Sheets to different formats\ngscli drive download \u003csheet-id\u003e --format xlsx     # Excel (all sheets)\ngscli drive download \u003csheet-id\u003e --format csv      # CSV (first sheet only)\ngscli drive download \u003csheet-id\u003e --format tsv      # TSV (first sheet only)\n\n# Export Google Slides\ngscli drive download \u003cslides-id\u003e --format pptx    # PowerPoint\n\n# Download to specific directory\ngscli drive download \u003cfile-id\u003e --output ./downloads\n\n# List comments on a file (unresolved only)\ngscli drive comments \u003cfile-id\u003e\n\n# List all comments including resolved\ngscli drive comments \u003cfile-id\u003e --include-resolved\n```\n\n### Google Calendar Commands\n\n```bash\n# List today's events\ngscli calendar list\n\n# List next 7 days\ngscli calendar list --range 7d\n\n# List next 2 weeks\ngscli calendar list --range 2w\n\n# List next month\ngscli calendar list --range 1m\n\n# Custom date range\ngscli calendar list --start \"2025-11-10\" --end \"2025-11-20\"\n\n# Search events\ngscli calendar search \"Team Meeting\"\ngscli calendar search \"1-on-1\"\n```\n\n## Use Cases for AI Agents\n\n### Example: Email Context for AI\n\n```bash\n# Get recent unread emails for AI to summarize\ngscli gmail search \"is:unread\" --limit 5\n\n# Find specific conversations\ngscli gmail search \"from:manager@company.com subject:project\"\n```\n\n### Example: Calendar Integration\n\n```bash\n# Get today's schedule for AI planning\ngscli calendar list\n\n# Check next week's meetings\ngscli calendar list --range 7d\n\n# Find specific meetings\ngscli calendar search \"standup\"\n```\n\n### Example: Document Access\n\n```bash\n# List recent documents\ngscli drive list --limit 10\n\n# List documents including those shared with you\ngscli drive list --include-shared --limit 20\n\n# Search for specific docs\ngscli drive search \"PRD\"\n\n# Download for AI processing\ngscli drive download \u003cfile-id\u003e --format pdf\n```\n\n## Architecture\n\n```\nsrc/\n├── index.ts              # CLI entry point\n├── commands/             # Command implementations\n│   ├── auth.ts          # Authentication commands\n│   ├── gmail.ts         # Gmail commands\n│   ├── drive.ts         # Drive commands\n│   └── calendar.ts      # Calendar commands\n└── lib/                 # Core library modules\n    ├── auth.ts          # OAuth2 authentication\n    ├── gmail.ts         # Gmail API wrapper\n    ├── drive.ts         # Drive API wrapper\n    ├── calendar.ts      # Calendar API wrapper\n    └── formatter.ts     # Output formatting\n```\n\n## Custom Build with Embedded Credentials\n\nFor advanced users who want to distribute a custom build with embedded OAuth2 credentials, you can inject your Google client credentials directly during the build process. This eliminates the need for users to provide credentials via the `--client` flag or environment variables.\n\n### Benefits\n\n- No need to distribute or manage `client.json` files\n- Users can authenticate immediately without additional setup\n- Ideal for internal tools or controlled distribution\n\n### Build Command\n\n```bash\n# 1. Export your credentials as environment variables\nexport GOOGLE_CLIENT_ID=\"your-client-id-here.apps.googleusercontent.com\"\nexport GOOGLE_CLIENT_SECRET=\"your-client-secret-here\"\n\n# 2. Build with embedded credentials\nbun run build:custom              # Build for current platform\nbun run build:custom-all          # Build for all platforms\nbun run build:custom-linux        # Build for Linux only\nbun run build:custom-macos        # Build for macOS only\nbun run build:custom-windows      # Build for Windows only\n```\n\nThe built binaries will be in the `dist/` folder with the `-custom` suffix (e.g., `dist/gscli-custom-linux`).\n\n### Important Notes\n\n- The credentials are embedded in the compiled binary at build time\n- Users of your custom build will still need to authenticate via OAuth2 (`gscli auth login`)\n- This is suitable for internal distribution or when you trust the users\n- For public distribution, it's recommended to let users provide their own credentials\n\n### Security Considerations\n\nWhen building with embedded credentials:\n- Only distribute to trusted users or within your organization\n- Consider the OAuth consent screen settings in Google Cloud Console\n- Users will authenticate with their own Google accounts, but using your OAuth2 app\n- Monitor usage through Google Cloud Console\n\n## Development\n\n```bash\n# Run in development mode\nbun run dev \u003ccommand\u003e\n\n# Example\nbun run dev gmail list\nbun run dev calendar list --range 7d\n\n# Build for production\nbun run build\n\n# Build for all platforms\nbun run build:all\n```\n\n## Security \u0026 Privacy\n\n- **Read-Only Access** - No write/delete operations possible\n- **Local Storage** - Credentials stored in `~/.config/gscli/`\n- **OAuth2 Standard** - Secure Google authentication\n- **Token Refresh** - Automatic token renewal\n- **No Data Collection** - Your data stays on your machine\n\n## API Scopes\n\nThe tool requests these read-only scopes:\n\n- `https://www.googleapis.com/auth/gmail.readonly`\n- `https://www.googleapis.com/auth/drive.readonly`\n- `https://www.googleapis.com/auth/calendar.readonly`\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Support\n\n- 🐛 Issues: [GitHub Issues](https://github.com/shaharia-lab/gscli/issues)\n- 💬 Discussions: [GitHub Discussions](https://github.com/shaharia-lab/gscli/discussions)\n\n## Credits\n\nBuilt with ❤️ by [Shaharia Lab](https://github.com/shaharia-lab)\n\nPowered by:\n- [Bun](https://bun.sh) - Fast JavaScript runtime\n- [TypeScript](https://www.typescriptlang.org/) - Type safety\n- [Google APIs](https://github.com/googleapis/google-api-nodejs-client) - Official Google API client\n- [Commander.js](https://github.com/tj/commander.js) - CLI framework\n- [Chalk](https://github.com/chalk/chalk) - Terminal styling\n- [Ora](https://github.com/sindresorhus/ora) - Terminal spinners\n\n---\n\n⭐ **Star us on GitHub:** [shaharia-lab/gscli](https://github.com/shaharia-lab/gscli)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaharia-lab%2Fgscli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshaharia-lab%2Fgscli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaharia-lab%2Fgscli/lists"}