gogcli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

gogcli - Google Workspace CLI

gogcli - Google Workspace 命令行工具

Overview

概述

gogcli is a comprehensive command-line interface for Google Workspace services. It provides fast, scriptable access to Gmail, Calendar, Drive, Docs, Sheets, Slides, Contacts, Tasks, Chat, Classroom, Groups, and Keep with JSON-first output and multi-account support.

gogcli是一款针对Google Workspace服务的全面命令行界面工具。它提供快速、可脚本化的方式访问Gmail、Calendar、Drive、Docs、Sheets、Slides、联系人、任务、Chat、Classroom、群组和Keep，支持优先JSON输出和多账户管理。

Quick Start

快速开始

Installation

安装

bash

undefined

bash

undefined

Homebrew

brew install steipete/tap/gogcli

From source

从源码安装

git clone https://github.com/steipete/gogcli.git cd gogcli make

undefined

git clone https://github.com/steipete/gogcli.git cd gogcli make

undefined

Initial Setup

初始配置

Prerequisites:

gcloud CLI installed and authenticated
Google account (Gmail or Workspace)

Automated setup (recommended):

bash

undefined

前置要求：

已安装并完成gcloud CLI的身份验证
Google账户（Gmail或Workspace）

自动化配置（推荐）：

bash

undefined

Run setup script to enable required APIs

运行配置脚本以启用所需API

Note: Set SKILL_ROOT to this skill's base directory (scripts are "$SKILL_ROOT/scripts/...").

注意：将SKILL_ROOT设置为该工具的基础目录（脚本路径为"$SKILL_ROOT/scripts/..."）。

bash "$SKILL_ROOT/scripts/setup_gcloud_project.sh" PROJECT_ID


**Manual setup:**

1. **Create or select Google Cloud project**:
   ```bash
   gcloud projects create PROJECT_ID --name="GoG CLI"
   gcloud config set project PROJECT_ID

Enable required APIs:

bash

# Core services
gcloud services enable \
  gmail.googleapis.com \
  calendar-json.googleapis.com \
  drive.googleapis.com \
  people.googleapis.com \
  --project=PROJECT_ID

For all services, see references/apis.md.

Configure OAuth consent screen:
- Open: https://console.cloud.google.com/apis/credentials/consent
- User Type: "External"
- App name: "gog CLI"
- Add test users: Your Gmail address
Create OAuth client:
- Open: https://console.cloud.google.com/apis/credentials/oauthclient
- Application type: "Desktop app"
- Name: "gog-cli"
- Download JSON credentials file

Validate credentials (optional):

bash

 bash "$SKILL_ROOT/scripts/validate_credentials.sh" ~/Downloads/client_secret_*.json

Store credentials:

bash

gog auth credentials ~/Downloads/client_secret_*.json

Authorize account:
bash
```
gog auth add you@gmail.com
```
If you see "Access blocked" error:
- Ensure your email is added as test user (step 3)
- Click "Advanced" → "Go to gog CLI (unsafe)"
- See references/troubleshooting.md for more

Test authentication:

bash

export GOG_ACCOUNT=you@gmail.com
gog gmail labels list
gog calendar calendars
gog drive ls --max 5

bash "$SKILL_ROOT/scripts/setup_gcloud_project.sh" PROJECT_ID


**手动配置：**

1. **创建或选择Google Cloud项目**:
   ```bash
   gcloud projects create PROJECT_ID --name="GoG CLI"
   gcloud config set project PROJECT_ID

启用所需API:

bash

# 核心服务
gcloud services enable \\
  gmail.googleapis.com \\
  calendar-json.googleapis.com \\
  drive.googleapis.com \\
  people.googleapis.com \\
  --project=PROJECT_ID

如需启用所有服务，请查看references/apis.md。

配置OAuth同意屏幕:
- 打开：https://console.cloud.google.com/apis/credentials/consent
- 用户类型："外部"
- 应用名称："gog CLI"
- 添加测试用户：你的Gmail地址
创建OAuth客户端:
- 打开：https://console.cloud.google.com/apis/credentials/oauthclient
- 应用类型："桌面应用"
- 名称："gog-cli"
- 下载JSON凭证文件

验证凭证（可选）:

bash

 bash "$SKILL_ROOT/scripts/validate_credentials.sh" ~/Downloads/client_secret_*.json

存储凭证:

bash

gog auth credentials ~/Downloads/client_secret_*.json

授权账户:
bash
```
gog auth add you@gmail.com
```
若出现"Access blocked"错误：
- 确保你的邮箱已添加为测试用户（步骤3）
- 点击"Advanced" → "Go to gog CLI (unsafe)"
- 更多内容请查看references/troubleshooting.md

测试身份验证:

bash

export GOG_ACCOUNT=you@gmail.com
gog gmail labels list
gog calendar calendars
gog drive ls --max 5

Core Capabilities

核心功能

1. Gmail Operations

1. Gmail操作

Search and read emails:

bash

undefined

搜索与读取邮件：

bash

undefined

Search threads

搜索会话

gog gmail search 'newer_than:7d' --max 10 gog gmail search 'is:unread from:alice@example.com'

Search messages (one per email)

搜索邮件（单条邮件为一个结果）

gog gmail messages search 'has:attachment' --max 10 --include-body

Get thread with attachments

获取带附件的会话

gog gmail thread get <threadId> --download --out-dir ./attachments

Get Gmail web URL

获取Gmail网页链接

gog gmail url <threadId>


**Send and compose:**
```bash

gog gmail url <threadId>


**发送与撰写邮件：**
```bash

Send plain text

发送纯文本邮件

gog gmail send --to a@b.com --subject "Hello" --body "Message"

Send HTML

发送HTML邮件

gog gmail send --to a@b.com --subject "Hello"
--body "Plain fallback"
--body-html "HTML content"

gog gmail send --to a@b.com --subject "Hello" \ --body "纯文本备用内容" \ --body-html "HTML内容"

Send with body from file or stdin

从文件或标准输入读取邮件内容发送

gog gmail send --to a@b.com --subject "Report" --body-file ./report.txt cat message.txt | gog gmail send --to a@b.com --subject "Data" --body-file -

Send with tracking (requires setup)

发送带追踪的邮件（需提前配置）

gog gmail send --to a@b.com --subject "Hello"
--body-html "Hi!" --track


**Manage labels and filters:**
```bash

gog gmail send --to a@b.com --subject "Hello" \ --body-html "你好！" --track


**管理标签与过滤器：**
```bash

List/create labels

列出/创建标签

gog gmail labels list gog gmail labels create "My Label"

gog gmail labels list gog gmail labels create "我的标签"

Modify thread labels

修改会话标签

gog gmail thread modify <threadId> --add STARRED --remove INBOX

Create filter

创建过滤器

gog gmail filters create --from 'noreply@example.com' --add-label 'Notifications'

gog gmail filters create --from 'noreply@example.com' --add-label '通知'

Batch operations

批量操作

gog gmail batch modify <msgId1> <msgId2> --add STARRED --remove INBOX


**Email tracking:**
```bash

gog gmail batch modify <msgId1> <msgId2> --add STARRED --remove INBOX


**邮件追踪：**
```bash

Setup tracking (generates tracking ID)

配置追踪（生成追踪ID）

gog gmail track setup --worker-url https://gog-email-tracker.<acct>.workers.dev

Check opens

查看打开记录

gog gmail track opens <tracking_id> gog gmail track opens --to recipient@example.com

undefined

gog gmail track opens <tracking_id> gog gmail track opens --to recipient@example.com

undefined

2. Calendar Management

2. 日历管理

List and search events:

bash

undefined

列出与搜索事件：

bash

undefined

Time-based queries

基于时间的查询

gog calendar events <calendarId> --today gog calendar events <calendarId> --tomorrow gog calendar events <calendarId> --week gog calendar events <calendarId> --days 3 gog calendar events <calendarId> --from today --to friday

Include weekday columns

包含星期列

gog calendar events <calendarId> --today --weekday

All calendars

所有日历

gog calendar events --all

Search

搜索事件

gog calendar search "meeting" --today


**Create and update events:**
```bash

gog calendar search "会议" --today


**创建与更新事件：**
```bash

Basic event

基础事件

gog calendar create <calendarId>
--summary "Meeting"
--from 2025-01-15T10:00:00Z
--to 2025-01-15T11:00:00Z

gog calendar create <calendarId> \ --summary "会议" \ --from 2025-01-15T10:00:00Z \ --to 2025-01-15T11:00:00Z

With attendees and location

带参会者与地点的事件

gog calendar create <calendarId>
--summary "Team Sync"
--from 2025-01-15T14:00:00Z
--to 2025-01-15T15:00:00Z
--attendees "alice@example.com,bob@example.com"
--location "Zoom"
--send-updates all

gog calendar create <calendarId> \ --summary "团队同步会" \ --from 2025-01-15T14:00:00Z \ --to 2025-01-15T15:00:00Z \ --attendees "alice@example.com,bob@example.com" \ --location "Zoom" \ --send-updates all

Recurring event with reminders

带提醒的重复事件

gog calendar create <calendarId>
--summary "Payment"
--from 2025-02-11T09:00:00-03:00
--to 2025-02-11T09:15:00-03:00
--rrule "RRULE:FREQ=MONTHLY;BYMONTHDAY=11"
--reminder "email:3d"
--reminder "popup:30m"

gog calendar create <calendarId> \ --summary "付款提醒" \ --from 2025-02-11T09:00:00-03:00 \ --to 2025-02-11T09:15:00-03:00 \ --rrule "RRULE:FREQ=MONTHLY;BYMONTHDAY=11" \ --reminder "email:3d" \ --reminder "popup:30m"

Add attendees (without replacing existing)

添加参会者（不替换现有参会者）

gog calendar update <calendarId> <eventId>
--add-attendee "alice@example.com,bob@example.com"


**Special event types:**
```bash

gog calendar update <calendarId> <eventId> \ --add-attendee "alice@example.com,bob@example.com"


**特殊事件类型：**
```bash

Focus time

专注时间

gog calendar focus-time --from 2025-01-15T13:00:00Z --to 2025-01-15T14:00:00Z

Out of office

外出

gog calendar out-of-office --from 2025-01-20 --to 2025-01-21 --all-day

Working location

工作地点

gog calendar working-location --type office --office-label "HQ"
--from 2025-01-22 --to 2025-01-23


**Team calendars and availability:**
```bash

gog calendar working-location --type office --office-label "总部" \ --from 2025-01-22 --to 2025-01-23


**团队日历与可用性：**
```bash

Team events (Workspace)

团队事件（Workspace）

gog calendar team <group-email> --today gog calendar team <group-email> --week --freebusy

Free/busy lookup

空闲/忙碌查询

gog calendar freebusy --calendars "primary,work@example.com"
--from 2025-01-15T00:00:00Z
--to 2025-01-16T00:00:00Z

gog calendar freebusy --calendars "primary,work@example.com" \ --from 2025-01-15T00:00:00Z \ --to 2025-01-16T00:00:00Z

Find conflicts

查找冲突

gog calendar conflicts --calendars "primary,work@example.com" --today


**Respond to invitations:**
```bash
gog calendar respond <calendarId> <eventId> --status accepted
gog calendar respond <calendarId> <eventId> --status declined --send-updates externalOnly

gog calendar conflicts --calendars "primary,work@example.com" --today


**回复邀请：**
```bash
gog calendar respond <calendarId> <eventId> --status accepted
gog calendar respond <calendarId> <eventId> --status declined --send-updates externalOnly

3. Drive Operations

3. Drive操作

Search and organize:

bash

undefined

搜索与整理：

bash

undefined

List and search

列出与搜索

gog drive ls --max 20 gog drive ls --parent <folderId> gog drive search "invoice" --max 20

gog drive ls --max 20 gog drive ls --parent <folderId> gog drive search "发票" --max 20

Get metadata and URL

获取元数据与链接

gog drive get <fileId> gog drive url <fileId>

Organize

整理文件

gog drive mkdir "New Folder" gog drive rename <fileId> "New Name" gog drive move <fileId> --parent <destinationFolderId> gog drive delete <fileId> gog drive copy <fileId> "Copy Name"


**Upload and download:**
```bash

gog drive mkdir "新文件夹" gog drive rename <fileId> "新名称" gog drive move <fileId> --parent <destinationFolderId> gog drive delete <fileId> gog drive copy <fileId> "副本名称"


**上传与下载：**
```bash

Upload

上传文件

gog drive upload ./path/to/file --parent <folderId>

Download

下载文件

gog drive download <fileId> --out ./file.bin

Export Google Workspace files

导出Google Workspace文件

gog drive download <fileId> --format pdf --out ./doc.pdf gog drive download <fileId> --format docx --out ./doc.docx gog drive download <fileId> --format pptx --out ./slides.pptx


**Permissions:**
```bash

gog drive download <fileId> --format pdf --out ./文档.pdf gog drive download <fileId> --format docx --out ./文档.docx gog drive download <fileId> --format pptx --out ./幻灯片.pptx


**权限管理：**
```bash

List permissions

列出权限

gog drive permissions <fileId>

分享文件

gog drive share <fileId> --email user@example.com --role reader gog drive share <fileId> --email user@example.com --role writer

Unshare

取消分享

gog drive unshare <fileId> --permission-id <permissionId>

undefined

gog drive unshare <fileId> --permission-id <permissionId>

undefined

4. Sheets Operations

4. Sheets操作

Read data:

bash

undefined

读取数据：

bash

undefined

Get metadata

获取元数据

gog sheets metadata <spreadsheetId>

Read range

读取指定范围

gog sheets get <spreadsheetId> 'Sheet1!A1:B10'


**Write data:**
```bash

gog sheets get <spreadsheetId> 'Sheet1!A1:B10'


**写入数据：**
```bash

Update cells (pipe-delimited for columns, comma for rows)

更新单元格（列用|分隔，行用,分隔）

gog sheets update <spreadsheetId> 'A1' 'val1|val2,val3|val4'

gog sheets update <spreadsheetId> 'A1' '值1|值2,值3|值4'

Update with JSON

用JSON格式更新

gog sheets update <spreadsheetId> 'A1' --values-json '[["a","b"],["c","d"]]'

Copy validation from another range

从其他范围复制验证规则

gog sheets update <spreadsheetId> 'Sheet1!A1:C1' 'new|row|data'
--copy-validation-from 'Sheet1!A2:C2'

gog sheets update <spreadsheetId> 'Sheet1!A1:C1' '新|行|数据' \ --copy-validation-from 'Sheet1!A2:C2'

Append rows

追加行

gog sheets append <spreadsheetId> 'Sheet1!A:C' 'new|row|data'

gog sheets append <spreadsheetId> 'Sheet1!A:C' '新|行|数据'

Clear range

清空指定范围

gog sheets clear <spreadsheetId> 'Sheet1!A1:B10'


**Format and create:**
```bash

gog sheets clear <spreadsheetId> 'Sheet1!A1:B10'


**格式化与创建：**
```bash

Format cells

格式化单元格

gog sheets format <spreadsheetId> 'Sheet1!A1:B2'
--format-json '{"textFormat":{"bold":true}}'
--format-fields 'userEnteredFormat.textFormat.bold'

gog sheets format <spreadsheetId> 'Sheet1!A1:B2' \ --format-json '{"textFormat":{"bold":true}}' \ --format-fields 'userEnteredFormat.textFormat.bold'

Create spreadsheet

创建电子表格

gog sheets create "My Spreadsheet" --sheets "Sheet1,Sheet2"

gog sheets create "我的电子表格" --sheets "Sheet1,Sheet2"

Export

导出

gog sheets export <spreadsheetId> --format pdf --out ./sheet.pdf

undefined

gog sheets export <spreadsheetId> --format pdf --out ./表格.pdf

undefined

5. Docs and Slides

5. Docs与Slides操作

Docs:

bash

undefined

Docs：

bash

undefined

Get info and extract text

获取信息与提取文本

gog docs info <docId> gog docs cat <docId> --max-bytes 10000

Create and copy

创建与复制

gog docs create "My Doc" gog docs copy <docId> "My Doc Copy"

gog docs create "我的文档" gog docs copy <docId> "我的文档副本"

Export

导出

gog docs export <docId> --format pdf --out ./doc.pdf gog docs export <docId> --format docx --out ./doc.docx gog docs export <docId> --format txt --out ./doc.txt


**Slides:**
```bash

gog docs export <docId> --format pdf --out ./文档.pdf gog docs export <docId> --format docx --out ./文档.docx gog docs export <docId> --format txt --out ./文档.txt


**Slides：**
```bash

Create and copy

创建与复制

gog slides create "My Deck" gog slides copy <presentationId> "My Deck Copy"

gog slides create "我的演示文稿" gog slides copy <presentationId> "我的演示文稿副本"

Export

导出

gog slides export <presentationId> --format pptx --out ./deck.pptx gog slides export <presentationId> --format pdf --out ./deck.pdf

undefined

gog slides export <presentationId> --format pptx --out ./演示文稿.pptx gog slides export <presentationId> --format pdf --out ./演示文稿.pdf

undefined

6. Contacts Management

6. 联系人管理

Personal contacts:

bash

undefined

个人联系人：

bash

undefined

List and search

列出与搜索

gog contacts list --max 50 gog contacts search "Ada" --max 50

gog contacts list --max 50 gog contacts search "艾达" --max 50

Get contact

获取联系人

gog contacts get people/<resourceName> gog contacts get user@example.com

Create contact

创建联系人

gog contacts create
--given-name "John"
--family-name "Doe"
--email "john@example.com"
--phone "+1234567890"

gog contacts create \ --given-name "约翰" \ --family-name "多伊" \ --email "john@example.com" \ --phone "+1234567890"

Update and delete

更新与删除联系人

gog contacts update people/<resourceName> --given-name "Jane" gog contacts delete people/<resourceName>


**Other contacts and directory (Workspace):**
```bash

gog contacts update people/<resourceName> --given-name "简" gog contacts delete people/<resourceName>


**其他联系人和目录（Workspace）：**
```bash

Other contacts (people you've interacted with)

其他联系人（你有过互动的用户）

gog contacts other list --max 50 gog contacts other search "John" --max 50

gog contacts other list --max 50 gog contacts other search "约翰" --max 50

Workspace directory

Workspace目录

gog contacts directory list --max 50 gog contacts directory search "Jane" --max 50

undefined

gog contacts directory list --max 50 gog contacts directory search "简" --max 50

undefined

7. Tasks

7. 任务管理

Manage task lists and tasks:

bash

undefined

管理任务列表与任务：

bash

undefined

Task lists

任务列表

gog tasks lists --max 50 gog tasks lists create "My Tasks"

gog tasks lists --max 50 gog tasks lists create "我的任务"

Tasks

任务

gog tasks list <tasklistId> --max 50 gog tasks get <tasklistId> <taskId>

Create tasks

创建任务

gog tasks add <tasklistId> --title "Task title" gog tasks add <tasklistId> --title "Weekly sync" --due 2025-02-01
--repeat weekly --repeat-count 4

gog tasks add <tasklistId> --title "任务标题" gog tasks add <tasklistId> --title "每周同步会" --due 2025-02-01 \ --repeat weekly --repeat-count 4

Manage tasks

管理任务

gog tasks update <tasklistId> <taskId> --title "New title" gog tasks done <tasklistId> <taskId> gog tasks undo <tasklistId> <taskId> gog tasks delete <tasklistId> <taskId> gog tasks clear <tasklistId>

undefined

gog tasks update <tasklistId> <taskId> --title "新标题" gog tasks done <tasklistId> <taskId> gog tasks undo <tasklistId> <taskId> gog tasks delete <tasklistId> <taskId> gog tasks clear <tasklistId>

undefined

8. Chat (Workspace)

8. Chat（Workspace）

Spaces and messages:

bash

undefined

空间与消息：

bash

undefined

List and create spaces

列出与创建空间

gog chat spaces list gog chat spaces find "Engineering" gog chat spaces create "Engineering"
--member alice@company.com
--member bob@company.com

gog chat spaces list gog chat spaces find "工程部" gog chat spaces create "工程部" \ --member alice@company.com \ --member bob@company.com

Messages

消息

gog chat messages list spaces/<spaceId> --max 5 gog chat messages list spaces/<spaceId> --unread gog chat messages send spaces/<spaceId> --text "Build complete!" gog chat messages send spaces/<spaceId> --text "Reply"
--thread spaces/<spaceId>/threads/<threadId>

gog chat messages list spaces/<spaceId> --max 5 gog chat messages list spaces/<spaceId> --unread gog chat messages send spaces/<spaceId> --text "构建完成！" gog chat messages send spaces/<spaceId> --text "回复" \ --thread spaces/<spaceId>/threads/<threadId>

Direct messages

直接消息

gog chat dm space user@company.com gog chat dm send user@company.com --text "ping"

undefined

gog chat dm space user@company.com gog chat dm send user@company.com --text "ping"

undefined

9. Classroom (Workspace for Education)

9. Classroom（教育版Workspace）

Courses:

bash

undefined

课程：

bash

undefined

List and manage courses

列出与管理课程

gog classroom courses list gog classroom courses get <courseId> gog classroom courses create --name "Math 101" gog classroom courses archive <courseId>


**Coursework and submissions:**
```bash

gog classroom courses list gog classroom courses get <courseId> gog classroom courses create --name "数学101" gog classroom courses archive <courseId>


**作业与提交：**
```bash

Coursework

作业

gog classroom coursework list <courseId> gog classroom coursework create <courseId>
--title "Homework 1"
--type ASSIGNMENT
--state PUBLISHED

gog classroom coursework list <courseId> gog classroom coursework create <courseId> \ --title "作业1" \ --type ASSIGNMENT \ --state PUBLISHED

Submissions

提交记录

gog classroom submissions list <courseId> <courseworkId> gog classroom submissions grade <courseId> <courseworkId> <submissionId> --grade 85 gog classroom submissions return <courseId> <courseworkId> <submissionId>

undefined

undefined

10. Groups and Keep (Workspace)

10. 群组与Keep（Workspace）

Groups:

bash

undefined

群组：

bash

undefined

List groups

列出群组

gog groups list

List members

列出群组成员

gog groups members engineering@company.com


**Keep (requires service account):**
```bash

gog groups members engineering@company.com


**Keep（需服务账户）：**
```bash

Setup service account first

先配置服务账户

gog auth service-account set you@yourdomain.com --key ~/service-account.json

List and search notes

列出与搜索笔记

gog keep list --account you@yourdomain.com gog keep search <query> --account you@yourdomain.com

Get note and download attachment

获取笔记与下载附件

gog keep get <noteId> --account you@yourdomain.com gog keep attachment <attachmentName> --account you@yourdomain.com --out ./file.bin

undefined

gog keep get <noteId> --account you@yourdomain.com gog keep attachment <attachmentName> --account you@yourdomain.com --out ./file.bin

undefined

Authentication and Configuration

身份验证与配置

Multiple Accounts

多账户管理

bash

undefined

bash

undefined

Add multiple accounts

添加多个账户

gog auth add personal@gmail.com gog auth add work@company.com

Use aliases

使用别名

gog auth alias set work work@company.com gog gmail search 'is:unread' --account work

Set default

设置默认账户

export GOG_ACCOUNT=work@company.com gog gmail search 'is:unread'

undefined

export GOG_ACCOUNT=work@company.com gog gmail search 'is:unread'

undefined

Multiple OAuth Clients (Workspace)

多OAuth客户端（Workspace）

bash

undefined

bash

undefined

Store named OAuth client

存储命名OAuth客户端

gog --client work auth credentials ~/work-client.json

Use with account

搭配账户使用

gog --client work auth add you@company.com

Auto-select by domain

按域名自动选择

gog --client work auth credentials ~/work.json --domain example.com

undefined

gog --client work auth credentials ~/work.json --domain example.com

undefined

Service Accounts (Workspace)

服务账户（Workspace）

For domain-wide delegation:

Create service account in Google Cloud Console
Enable domain-wide delegation
Download JSON key
Allowlist scopes in Workspace Admin Console
Configure gogcli:

bash

gog auth service-account set you@yourdomain.com --key ~/service-account.json
gog --account you@yourdomain.com auth status

如需域范围委派：

在Google Cloud控制台创建服务账户
启用域范围委派
下载JSON密钥
在Workspace管理控制台允许相关范围
配置gogcli：

bash

gog auth service-account set you@yourdomain.com --key ~/service-account.json
gog --account you@yourdomain.com auth status

Service Scopes

服务范围

bash

undefined

bash

undefined

Request specific services

请求特定服务

gog auth add you@gmail.com --services drive,calendar

Read-only scopes

只读范围

gog auth add you@gmail.com --services drive,calendar --readonly

Drive scope control

Drive范围控制

gog auth add you@gmail.com --services drive --drive-scope readonly

Add services later (force consent if needed)

后续添加服务（如需强制重新授权）

gog auth add you@gmail.com --services sheets --force-consent

undefined

gog auth add you@gmail.com --services sheets --force-consent

undefined

Keyring Backend

密钥环后端

bash

undefined

bash

undefined

Show current backend

显示当前后端

gog auth keyring

Set backend

设置后端

gog auth keyring file # Encrypted on-disk gog auth keyring keychain # macOS Keychain gog auth keyring auto # Best available

gog auth keyring file # 磁盘加密存储 gog auth keyring keychain # macOS钥匙串 gog auth keyring auto # 自动选择最佳后端

For non-interactive use (file backend)

非交互式使用（文件后端）

export GOG_KEYRING_PASSWORD='...' gog --no-input auth status

undefined

export GOG_KEYRING_PASSWORD='...' gog --no-input auth status

undefined

Output Formats

输出格式

JSON Output (for scripting)

JSON输出（用于脚本）

bash

undefined

bash

undefined

Enable JSON output

启用JSON输出

gog gmail search 'newer_than:7d' --max 3 --json gog calendar events primary --today --json

Use with jq

搭配jq使用

gog --json drive ls --max 5 | jq '.files[] | select(.mimeType=="application/pdf")'

Environment variable

环境变量设置

export GOG_JSON=1 gog gmail search 'is:unread'

undefined

export GOG_JSON=1 gog gmail search 'is:unread'

undefined

Plain Text (TSV)

纯文本（TSV）

bash

undefined

bash

undefined

Stable, parseable output

稳定、可解析的输出

gog gmail search 'newer_than:7d' --plain gog calendar events primary --today --plain

undefined

gog gmail search 'newer_than:7d' --plain gog calendar events primary --today --plain

undefined

Human-Friendly (default)

人性化格式（默认）

Colored tables on stdout, progress/hints on stderr.

标准输出为带颜色的表格，进度/提示信息输出到标准错误流。

Common Patterns

常见使用场景

Email Automation

邮件自动化

bash

undefined

bash

undefined

Search and download attachments

搜索并下载附件

gog gmail search 'newer_than:7d has:attachment' --max 10 gog gmail thread get <threadId> --download

Batch label management

批量管理标签

gog --json gmail search 'from:noreply@example.com' --max 200 |
jq -r '.threads[].id' |
xargs -n 50 gog gmail labels modify --remove UNREAD

gog --json gmail search 'from:noreply@example.com' --max 200 | \ jq -r '.threads[].id' | \ xargs -n 50 gog gmail labels modify --remove UNREAD

Archive old emails

归档旧邮件

gog --json gmail search 'older_than:1y' --max 200 |
jq -r '.threads[].id' |
xargs -n 50 gog gmail labels modify --remove INBOX

undefined

gog --json gmail search 'older_than:1y' --max 200 | \ jq -r '.threads[].id' | \ xargs -n 50 gog gmail labels modify --remove INBOX

undefined

Calendar Integration

日历集成

bash

undefined

bash

undefined

Find free time and create meeting

查找空闲时间并创建会议

gog calendar freebusy --calendars "primary"
--from 2025-01-15T00:00:00Z --to 2025-01-16T00:00:00Z

gog calendar create primary
--summary "Team Standup"
--from 2025-01-15T10:00:00Z
--to 2025-01-15T10:30:00Z
--attendees "alice@example.com,bob@example.com"

undefined

gog calendar freebusy --calendars "primary" \ --from 2025-01-15T00:00:00Z --to 2025-01-16T00:00:00Z

gog calendar create primary \ --summary "团队站会" \ --from 2025-01-15T10:00:00Z \ --to 2025-01-15T10:30:00Z \ --attendees "alice@example.com,bob@example.com"

undefined

File Operations

文件操作

bash

undefined

bash

undefined

Search and download PDFs

搜索并下载PDF文件

gog drive search "invoice filetype:pdf" --max 20 --json |
jq -r '.files[] | .id' |
while read fileId; do gog drive download "$fileId" done

undefined

gog drive search "invoice filetype:pdf" --max 20 --json | \ jq -r '.files[] | .id' | \ while read fileId; do gog drive download "$fileId" done

undefined

Sheets Data Management

Sheets数据管理

bash

undefined

bash

undefined

Update sheet from CSV

从CSV更新表格

cat data.csv | tr ',' '|' |
gog sheets update <spreadsheetId> 'Sheet1!A1'

cat data.csv | tr ',' '|' | \ gog sheets update <spreadsheetId> 'Sheet1!A1'

Read and process with jq

读取数据并用jq处理

gog sheets get <spreadsheetId> 'Sheet1!A1:B10' --json |
jq '.values'

undefined

gog sheets get <spreadsheetId> 'Sheet1!A1:B10' --json | \ jq '.values'

undefined

Global Flags and Environment

全局标志与环境变量

Flags:

```
--account <email|alias|auto>
```
- Account to use
```
--client <name>
```
- OAuth client name
```
--json
```
- JSON output
```
--plain
```
- Plain text output (TSV)
```
--color <mode>
```
- Color mode (auto/always/never)
```
--force
```
- Skip confirmations
```
--no-input
```
- Never prompt (fail instead)
```
--verbose
```
- Verbose logging
```
--enable-commands <csv>
```
- Command allowlist for sandboxing

Environment variables:

```
GOG_ACCOUNT
```
- Default account
```
GOG_CLIENT
```
- OAuth client
```
GOG_JSON
```
- Default JSON output
```
GOG_PLAIN
```
- Default plain output
```
GOG_COLOR
```
- Color mode
```
GOG_TIMEZONE
```
- Default timezone
```
GOG_ENABLE_COMMANDS
```
- Command allowlist
```
GOG_KEYRING_BACKEND
```
- Keyring backend
```
GOG_KEYRING_PASSWORD
```
- Keyring password

标志：

```
--account <email|alias|auto>
```
- 使用的账户
```
--client <name>
```
- OAuth客户端名称
```
--json
```
- 输出JSON格式
```
--plain
```
- 输出纯文本格式（TSV）
```
--color <mode>
```
- 颜色模式（auto/always/never）
```
--force
```
- 跳过确认步骤
```
--no-input
```
- 从不提示（失败则终止）
```
--verbose
```
- 详细日志
```
--enable-commands <csv>
```
- 命令白名单（沙箱模式）

环境变量：

```
GOG_ACCOUNT
```
- 默认账户
```
GOG_CLIENT
```
- OAuth客户端
```
GOG_JSON
```
- 默认输出JSON格式
```
GOG_PLAIN
```
- 默认输出纯文本格式
```
GOG_COLOR
```
- 颜色模式
```
GOG_TIMEZONE
```
- 默认时区
```
GOG_ENABLE_COMMANDS
```
- 命令白名单
```
GOG_KEYRING_BACKEND
```
- 密钥环后端
```
GOG_KEYRING_PASSWORD
```
- 密钥环密码

Reference Documentation

参考文档

Command reference: references/commands.md - Comprehensive command reference with all options
API and scopes: references/apis.md - Required APIs and OAuth scopes by service
Troubleshooting: references/troubleshooting.md - Common issues and solutions

命令参考：references/commands.md - 包含所有选项的全面命令参考
API与范围：references/apis.md - 各服务所需的API与OAuth范围
故障排除：references/troubleshooting.md - 常见问题与解决方案

Tips and Best Practices

技巧与最佳实践

Use JSON output for scripting - Combine with
```
jq
```
for powerful pipelines
Set default account - Use
```
GOG_ACCOUNT
```
to avoid repeating
```
--account
```
Use aliases - Create short aliases for frequently used accounts
Batch operations - Use
```
xargs
```
with JSON output for bulk operations
Time zones - Use
```
--timezone
```
or
```
GOG_TIMEZONE
```
for consistent calendar output
Service scopes - Request only needed scopes with
```
--services
```
Keyring backend - Use
```
file
```
backend for CI/containers
Command sandboxing - Use
```
--enable-commands
```
for agent runs
Read-only access - Use
```
--readonly
```
flag when appropriate
Error handling - Use
```
--no-input
```
for non-interactive scripts

脚本使用JSON输出 - 搭配
```
jq
```
实现强大的流水线操作
设置默认账户 - 使用
```
GOG_ACCOUNT
```
避免重复输入
```
--account
```
使用别名 - 为常用账户创建短别名
批量操作 - 结合JSON输出与
```
xargs
```
实现批量操作
时区设置 - 使用
```
--timezone
```
或
```
GOG_TIMEZONE
```
确保日历输出一致
服务范围 - 使用
```
--services
```
仅请求所需的范围
密钥环后端 - 在CI/容器中使用
```
file
```
后端
命令沙箱 - 代理运行时使用
```
--enable-commands
```
只读访问 - 适当场景下使用
```
--readonly
```
标志
错误处理 - 非交互式脚本使用
```
--no-input
```