gworkspace-cli

通过终端命令 gw 管理 Google Drive、Docs 和 Sheets。

请先执行以下操作

• 确保已安装 gw：npm i -g @11x.agency/gworkspace
• 确保已完成身份验证：运行 gw auth --status。若未认证，请运行 gw auth。
• 若目标为 Shared Drive，请先获取其 drive ID：gw drive shared

身份验证

gw auth                 # 打开浏览器进行 Google 登录
gw auth --status        # 检查当前认证状态（邮箱、授权范围、过期时间）
gw logout               # 删除已保存的凭据

Token 存储于 ~/.11x/gworkspace/token.json。OAuth 凭据可通过环境变量或 .env 文件提供：

• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
• GW_CLIENT_ID / GW_CLIENT_SECRET（别名）

命令

Drive

# 列出文件
gw drive ls                              # My Drive 根目录
gw drive ls /Projects                    # 按路径列出
gw drive ls --folder                # 按文件夹 ID 列出
gw drive ls --type doc                  # 过滤类型：doc、sheet、folder、all
gw drive ls --limit 50                  # 分页限制

# 创建文件夹
gw drive mkdir "文件夹名称"
gw drive mkdir "子文件夹" --folder <父文件夹 ID>

# 搜索
gw drive search "季度报告"
gw drive search "预算" --type sheet

# 上传
gw drive upload ./file.pdf
gw drive upload ./data.csv --folder  --name "Q4 数据"

# 列出 Shared Drive
gw drive shared

Shared Drives

在任意子命令前使用全局标志 --drive ：

gw --drive  drive ls
gw --drive  drive ls /Projects
gw --drive  drive mkdir "新文件夹"
gw --drive  drive search "报告"
gw --drive  drive upload ./file.pdf

如需在 Shared Drive 中创建 Docs 或 Sheets，请配合使用 --folder 参数并传入 Shared Drive 内某文件夹的 ID：

gw doc create "标题" --folder 
gw sheet create "标题" --folder 

Docs

gw doc read                     # 输出纯文本
gw doc read  --markdown         # 输出 Markdown 格式
gw doc create "标题"                   # 创建空文档，返回 ID 与 URL
gw doc create "标题" --folder      # 在指定文件夹中创建
gw doc append  "文本"           # 向文档末尾追加文本
gw doc append  --file ./notes.txt  # 从文件追加内容

Sheets

gw sheet read                   # 读取首个工作表全部数据（JSON 行格式）
gw sheet read  "Sheet1!A1:C10"  # 读取指定范围
gw sheet write  "A1:B2" '[["姓名","分数"],["Alice","95"]]'
gw sheet write  "A1" --file ./data.csv
gw sheet append  '[["Bob","88"]]'
gw sheet append  --file ./more.csv
gw sheet create "标题"                 # 创建电子表格
gw sheet create "标题" --folder 
gw sheet list                   # 列出所有工作表（tabs/sheets）

输出模式

所有命令均支持三种输出模式：

I/O 协议

• stdout：数据输出（JSON、表格或 ID）
• stderr：错误信息、状态提示、进度信息
• 退出码 0：成功
• 退出码 1：任意错误（认证失败、资源未找到、权限不足、网络异常等）

URL 与 ID

所有命令均接受完整 Google URL 或仅 ID —— 可直接粘贴完整链接，也可仅提供 ID：

gw doc read https://docs.google.com/document/d/1abc.../edit
gw doc read 1abc...

错误信息

常见 Agent 工作流

浏览 Shared Drive 并读取一份文档

gw drive shared --quiet                          # 获取 Shared Drive ID 列表
gw --drive  drive ls --pretty                # 浏览根目录（表格格式）
gw --drive  drive ls --folder     # 进入子文件夹
gw doc read                              # 读取文档内容

在指定文件夹中创建含内容的文档

gw drive mkdir "Project X"                       # 创建文件夹，获取其 ID
gw doc create "Requirements" --folder        # 创建文档，获取其 ID
gw doc append  "# Requirementsnn..."   # 写入内容

导出 Sheet 数据用于后续处理

gw sheet read  --quiet > data.tsv            # 导出为制表符分隔的文件
gw sheet read  "Sheet1!A1:D100" | jq '.'     # 输出 JSON，供 jq 等工具处理

上传并组织文件

gw drive mkdir "Reports" --folder 
gw drive upload ./q4-report.pdf --folder  --name "Q4 Report 2026"