Back to Details

gog-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

gogcli (gog) CLI

gogcli (gog) CLI

A fast, script-friendly CLI for Google Workspace services with JSON-first output and multi-account support.
Repository: https://github.com/steipete/gogcli
这是一款适用于Google Workspace服务的快速、支持脚本的CLI工具，优先输出JSON格式，且支持多账户管理。
仓库地址: https://github.com/steipete/gogcli

Prerequisites

前提条件

This skill assumes 
gog
is installed and authorised. If commands fail with authentication errors, inform the user they need to:
  1. Install gog: 
    brew install steipete/tap/gogcli
  2. Store OAuth credentials: 
    gog auth credentials <path-to-credentials.json>
  3. Add account: 
    gog auth add user@gmail.com --services all
Do not attempt to resolve authentication issues automatically. Provide the user with the relevant command and let them handle it.
本技能默认
gog
已完成安装和授权。如果命令因认证错误失败，请告知用户需要执行以下步骤：
  1. 安装gog: 
    brew install steipete/tap/gogcli
  2. 存储OAuth凭据: 
    gog auth credentials <path-to-credentials.json>
  3. 添加账户: 
    gog auth add user@gmail.com --services all
请勿尝试自动解决认证问题。请为用户提供相关命令，让他们自行处理。

Supported Services

支持的服务

Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat (Workspace), Classroom, Contacts, Tasks, People, Groups (Workspace), Keep (Workspace, service account only).
Gmail、Calendar、Drive、Docs、Sheets、Slides、Chat (Workspace)、Classroom、Contacts、Tasks、People、Groups (Workspace)、Keep (Workspace，仅支持服务账户)。

Quick Reference

快速参考

Global Flags

全局标志

bash
--account <email>    # Select account
--client <name>      # Select OAuth client
--json               # JSON output
--plain              # TSV output (for scripting)
--force              # Skip confirmations
--no-input           # Fail instead of prompting
bash
--account <email>    # Select account
--client <name>      # Select OAuth client
--json               # JSON output
--plain              # TSV output (for scripting)
--force              # Skip confirmations
--no-input           # Fail instead of prompting

Common Patterns

常用示例

bash
gog --account work@example.com gmail search "is:unread"  # Use specific account
gog gmail search "is:unread" --json | jq '.threads[].id' # JSON for parsing
gog gmail search "is:unread" --plain | cut -f1           # Plain for shell
gog gmail search "is:unread" --max 10 --page <token>     # Pagination
bash
gog --account work@example.com gmail search "is:unread"  # Use specific account
gog gmail search "is:unread" --json | jq '.threads[].id' # JSON for parsing
gog gmail search "is:unread" --plain | cut -f1           # Plain for shell
gog gmail search "is:unread" --max 10 --page <token>     # Pagination

Gmail

Gmail

Search and Read

搜索与读取

bash
gog gmail search "is:unread from:boss@example.com newer_than:7d"
gog gmail messages search "is:unread" --include-body
gog gmail thread get <threadId>
gog gmail get <messageId> --format full
bash
gog gmail search "is:unread from:boss@example.com newer_than:7d"
gog gmail messages search "is:unread" --include-body
gog gmail thread get <threadId>
gog gmail get <messageId> --format full

Send Email

发送邮件

bash
undefined
bash
undefined

Basic send

Basic send

gog gmail send --to user@example.com --subject "Hello" --body "Message"
gog gmail send --to user@example.com --subject "Hello" --body "Message"

With HTML and attachments

With HTML and attachments

gog gmail send --to user@example.com --subject "Report"
--body-html "<h1>Report</h1>" --attach ~/report.pdf
gog gmail send --to user@example.com --subject "Report"
--body-html "<h1>Report</h1>" --attach ~/report.pdf

Reply

Reply

gog gmail send --to user@example.com --subject "Re: Original"
--body "Reply" --reply-to-message-id <messageId>
undefined
gog gmail send --to user@example.com --subject "Re: Original"
--body "Reply" --reply-to-message-id <messageId>
undefined

Labels

标签

bash
gog gmail labels list
gog gmail labels create "Project/Subproject"
gog gmail thread modify <threadId> --add "Label" --remove INBOX
For full Gmail reference including drafts, filters, vacation, delegates, tracking, and watch, see 
references/gmail.md
.
bash
gog gmail labels list
gog gmail labels create "Project/Subproject"
gog gmail thread modify <threadId> --add "Label" --remove INBOX
有关Gmail的完整说明（包括草稿、过滤器、休假回复、委托、追踪和监听），请查看
references/gmail.md
。

Calendar

Calendar

Events

事件

bash
gog calendar events primary --from "2024-12-01" --to "2024-12-31" --weekday
gog calendar events primary --query "meeting"
bash
gog calendar events primary --from "2024-12-01" --to "2024-12-31" --weekday
gog calendar events primary --query "meeting"

Create event

Create event

gog calendar create primary --summary "Meeting"
--from "2024-12-20T14:00:00" --to "2024-12-20T15:00:00"
gog calendar create primary --summary "Meeting"
--from "2024-12-20T14:00:00" --to "2024-12-20T15:00:00"

With attendees and recurrence

With attendees and recurrence

gog calendar create primary --summary "Weekly Standup"
--from "2024-12-20T09:00:00" --to "2024-12-20T09:30:00"
--attendees "alice@example.com,bob@example.com"
--rrule "FREQ=WEEKLY;BYDAY=MO,WE,FR"
gog calendar create primary --summary "Weekly Standup"
--from "2024-12-20T09:00:00" --to "2024-12-20T09:30:00"
--attendees "alice@example.com,bob@example.com"
--rrule "FREQ=WEEKLY;BYDAY=MO,WE,FR"

Respond

Respond

gog calendar respond primary <eventId> --status accepted
undefined
gog calendar respond primary <eventId> --status accepted
undefined

Special Event Types

特殊事件类型

bash
gog calendar focus-time create primary --from DT --to DT --auto-decline
gog calendar ooo create primary --from DT --to DT --decline-message "Away"
gog calendar working-location create primary --from DT --to DT --location home
For full Calendar reference, see 
references/calendar.md
.
bash
gog calendar focus-time create primary --from DT --to DT --auto-decline
gog calendar ooo create primary --from DT --to DT --decline-message "Away"
gog calendar working-location create primary --from DT --to DT --location home
有关Calendar的完整说明，请查看
references/calendar.md
。

Drive, Docs, Sheets, Slides

Drive、Docs、Sheets、Slides

Drive

Drive

bash
gog drive ls --parent <folderId>
gog drive search "quarterly report"
gog drive download <fileId> --out ~/Downloads/
gog drive upload ~/report.pdf --parent <folderId>
gog drive mkdir "New Folder" --parent <folderId>
gog drive share <fileId> --email user@example.com --role writer
bash
gog drive ls --parent <folderId>
gog drive search "quarterly report"
gog drive download <fileId> --out ~/Downloads/
gog drive upload ~/report.pdf --parent <folderId>
gog drive mkdir "New Folder" --parent <folderId>
gog drive share <fileId> --email user@example.com --role writer

Sheets

Sheets

bash
gog sheets read <spreadsheetId> "Sheet1!A1:D10"
gog sheets write <spreadsheetId> "Sheet1!A1:B2" --values '[["Name","Age"],["Alice",30]]'
gog sheets append <spreadsheetId> "Sheet1!A:B" --values '[["Bob",25]]'
gog sheets format <spreadsheetId> "Sheet1!A1:D1" --bold --bg-color "#FFCC00"
bash
gog sheets read <spreadsheetId> "Sheet1!A1:D10"
gog sheets write <spreadsheetId> "Sheet1!A1:B2" --values '["Name","Age"],["Alice",30]]'
gog sheets append <spreadsheetId> "Sheet1!A:B" --values '["Bob",25]]'
gog sheets format <spreadsheetId> "Sheet1!A1:D1" --bold --bg-color "#FFCC00"

Export

导出

bash
gog docs export <documentId> --format pdf --out ~/doc.pdf
gog slides export <presentationId> --format pptx --out ~/slides.pptx
For full Drive/Docs/Sheets/Slides reference, see 
references/drive-docs.md
.
bash
gog docs export <documentId> --format pdf --out ~/doc.pdf
gog slides export <presentationId> --format pptx --out ~/slides.pptx
有关Drive/Docs/Sheets/Slides的完整说明，请查看
references/drive-docs.md
。

Tasks

Tasks

bash
gog tasks lists
gog tasks list <tasklistId>
gog tasks add <tasklistId> --title "Buy groceries" --due "2024-12-20"
gog tasks add <tasklistId> --title "Weekly review" --due "2024-12-20" --repeat weekly
gog tasks done <tasklistId> <taskId>
bash
gog tasks lists
gog tasks list <tasklistId>
gog tasks add <tasklistId> --title "Buy groceries" --due "2024-12-20"
gog tasks add <tasklistId> --title "Weekly review" --due "2024-12-20" --repeat weekly
gog tasks done <tasklistId> <taskId>

Contacts

Contacts

bash
gog contacts search "john"
gog contacts create --given "John" --family "Doe" --email "john@example.com"
gog contacts directory search "smith"  # Workspace
bash
gog contacts search "john"
gog contacts create --given "John" --family "Doe" --email "john@example.com"
gog contacts directory search "smith"  # Workspace

Classroom

Classroom

bash
gog classroom courses --state ACTIVE
gog classroom students <courseId>
gog classroom coursework create <courseId> --title "Homework" --type ASSIGNMENT --due "2024-12-31T23:59:59Z"
gog classroom submissions grade <courseId> <courseworkId> <submissionId> --grade 95
For Classroom, Chat, Contacts, Tasks, People, Groups, Keep, see 
references/other-services.md
.
bash
gog classroom courses --state ACTIVE
gog classroom students <courseId>
gog classroom coursework create <courseId> --title "Homework" --type ASSIGNMENT --due "2024-12-31T23:59:59Z"
gog classroom submissions grade <courseId> <courseworkId> <submissionId> --grade 95
有关Classroom、Chat、Contacts、Tasks、People、Groups、Keep的说明，请查看
references/other-services.md
。

Configuration

配置

Config Locations

配置文件位置

  • macOS: 
    ~/Library/Application Support/gogcli/config.json
  • Linux: 
    ~/.config/gogcli/config.json
  • Windows: 
    %AppData%\gogcli\config.json
  • macOS: 
    ~/Library/Application Support/gogcli/config.json
  • Linux: 
    ~/.config/gogcli/config.json
  • Windows: 
    %AppData%\gogcli\config.json

Settings

设置

bash
gog config set default_timezone America/New_York
gog config set default_account user@gmail.com
gog config list
bash
gog config set default_timezone America/New_York
gog config set default_account user@gmail.com
gog config list

Environment Variables

环境变量

bash
GOG_ACCOUNT=user@gmail.com      # Default account
GOG_CLIENT=work                 # OAuth client
GOG_JSON=1                      # Default JSON output
GOG_PLAIN=1                     # Default plain output
GOG_TIMEZONE=America/New_York   # Display timezone
GOG_ENABLE_COMMANDS=calendar,tasks  # Command allowlist
For full configuration, see 
references/configuration.md
.
bash
GOG_ACCOUNT=user@gmail.com      # Default account
GOG_CLIENT=work                 # OAuth client
GOG_JSON=1                      # Default JSON output
GOG_PLAIN=1                     # Default plain output
GOG_TIMEZONE=America/New_York   # Display timezone
GOG_ENABLE_COMMANDS=calendar,tasks  # Command allowlist
有关完整配置说明，请查看
references/configuration.md
。

Multi-Account Usage

多账户使用

bash
gog --account work@example.com gmail search "is:unread"
gog auth alias set work work@example.com
gog --account work gmail search "is:unread"
gog auth list --check
For authentication including service accounts, see 
references/authentication.md
.
bash
gog --account work@example.com gmail search "is:unread"
gog auth alias set work work@example.com
gog --account work gmail search "is:unread"
gog auth list --check
有关认证（包括服务账户）的说明，请查看
references/authentication.md
。

Scripting

脚本编写

bash
undefined
bash
undefined

JSON processing

JSON processing

gog gmail search "is:unread" --json | jq -r '.threads[].id'
gog gmail search "is:unread" --json | jq -r '.threads[].id'

Batch operations

Batch operations

gog gmail search "older_than:30d" --json |
jq -r '.threads[].id' |
xargs -I {} gog gmail thread modify {} --add Archive --remove INBOX
gog gmail search "older_than:30d" --json |
jq -r '.threads[].id' |
xargs -I {} gog gmail thread modify {} --add Archive --remove INBOX

Non-interactive

Non-interactive

gog gmail send --to user@example.com --subject "Test" --body "Hi" --force
undefined
gog gmail send --to user@example.com --subject "Test" --body "Hi" --force
undefined

Troubleshooting

故障排除

If commands fail, inform the user of the likely cause:
ErrorCauseSolution
no credentials
OAuth not configured
gog auth credentials <file>
token expired
Auth invalid
gog auth add <email> --force-consent
insufficient scope
Missing permissions
gog auth add <email> --services <services>
command not found
Not installed
brew install steipete/tap/gogcli
Status checks:
bash
gog auth list --check
gog auth status
如果命令执行失败，请告知用户可能的原因：
错误原因解决方案
no credentials
未配置OAuth
gog auth credentials <file>
token expired
认证无效
gog auth add <email> --force-consent
insufficient scope
权限不足
gog auth add <email> --services <services>
command not found
未安装
brew install steipete/tap/gogcli
状态检查：
bash
gog auth list --check
gog auth status

Reference Files

参考文档

  • references/command-reference.md
    - Complete command specification
  • references/authentication.md
    - Auth, credentials, multi-account
  • references/configuration.md
    - Config and environment variables
  • references/gmail.md
    - Gmail operations
  • references/calendar.md
    - Calendar operations
  • references/drive-docs.md
    - Drive, Docs, Sheets, Slides
  • references/other-services.md
    - Classroom, Chat, Contacts, Tasks, People, Groups, Keep
  • references/command-reference.md
    - 完整命令说明
  • references/authentication.md
    - 认证、凭据、多账户
  • references/configuration.md
    - 配置与环境变量
  • references/gmail.md
    - Gmail操作
  • references/calendar.md
    - Calendar操作
  • references/drive-docs.md
    - Drive、Docs、Sheets、Slides
  • references/other-services.md
    - Classroom、Chat、Contacts、Tasks、People、Groups、Keep