gogcli Keep完全指南：域范围委托下管理Keep笔记的正确姿势

gogcli Keep完全指南：域范围委托下管理Keep笔记的正确姿势

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli

gogcli是一个把 Google Workspace 装进终端的命令行工具，其gog keep子命令支持在终端里直接管理 Keep 笔记：列出、查看、搜索、创建、删除笔记，还能下载附件。对于个人版 gmail.com 账号，Keep 接口不可用；企业/教育域（Workspace）用户则可以通过域范围委托（domain-wide delegation）+ 服务账号的方式，完全无人值守地批量管理 Keep 笔记。

为什么用 gogcli 管理 Keep 笔记

• 🖥️纯终端操作：无需打开网页，一条命令完成 Keep 笔记的增删查改
• 🤖脚本友好：-j输出 JSON、-p输出 TSV，方便接入自动化流程
• 🔒分层安全：支持--dry-run预演、--readonly只读拦截，误操作风险低
• 🏢Workspace 原生：面向企业域场景，可结合服务账号代理任意域内用户

前置条件：配置域范围委托

Keep API 属于 Workspace 专属能力，且服务账号本身在域内没有"身份"，必须借助域范围委托代理某个真实用户（--impersonate）来调用。

第 1 步：在服务账号上开启域范围委托

在 Google Cloud 控制台的 OAuth 客户端中，添加 Keep 所需的授权范围（scope），并填写你的域邮箱。gogcli 可以用下面命令列出服务账号可代理的授权范围：

gog auth services --json

第 2 步：保存服务账号密钥

gog auth service-account set svc@mycompany.iam.gserviceaccount.com \ --key ~/Downloads/service-account.json gog auth service-account status svc@mycompany.iam.gserviceaccount.com

第 3 步：指定代理用户运行 keep 命令

每条 keep 命令都支持这两个核心参数：

例如以域内zhang@example.com的身份列出其 Keep 笔记：

gog keep list \ --service-account ~/sa.json \ --impersonate zhang@example.com

💡 如果已执行过gog auth service-account set，密钥已按账号存储，日常使用时可直接通过-a指定该账号，无需每次传--service-account。

gog keep 五大命令速览

完整命令参考见 gog-keep.md，实现源码在 keep.go。

1. 列出笔记：gog keep list

gog keep list --impersonate zhang@example.com --all --max 200

• 默认返回 100 条，用--all可翻页取全量
• --filter支持服务端过滤表达式，例如只取某天之后的笔记：

gog keep list --filter 'create_time > "2026-01-01T00:00:00Z"'

• --fail-empty：无结果时以退出码 3 结束，适合脚本中判断"是否还有笔记"

2. 查看单条：gog keep get

gog keep get <noteId> --json

输出标题、正文、标签、附件名称等完整字段，-j可直接被 jq 或脚本消费。

3. 搜索笔记：gog keep search

gog keep search 报销 --max 500

搜索是客户端过滤：先拉取最多 500 条（--max可调），再在本地对标题和正文做匹配。笔记量很大时建议配合list --filter缩小范围。

4. 创建笔记：gog keep create

# 普通文本笔记 gog keep create --title "周会要点" --text "Q3 目标对齐" --impersonate zhang@example.com # 清单（checklist）笔记：--item 可重复 gog keep create --title "发布检查" \ --item "回归测试通过" \ --item "更新 CHANGELOG" \ --impersonate zhang@example.com

5. 删除笔记：gog keep delete

gog keep delete <noteId> --dry-run # 先预演，不真正删除 gog keep delete <noteId> -y # 确认无误后执行

删除属于破坏性操作，-y/--force跳过确认。

6. 下载附件：gog keep attachment

gog keep attachment <attachmentName> --out ./pic.jpg --mime-type image/jpeg

先通过get --json拿到笔记里的attachmentName，再用此命令落盘。

域范围委托的常用安全参数

在代理他人操作时，强烈建议配合以下"保险丝"：

一个稳妥的自动化习惯：先用--readonly验证账号与委托配置能正确读到笔记，再放开写操作。

常见问题排查

Q1：报权限或 403 错误？检查 OAuth 客户端的域范围委托里是否添加了对应的 Keep scope，且--impersonate的用户必须是域内真实存在的账号。

Q2：个人 Gmail 账号能用吗？不能。gog keep依赖 Keep API，属于 Workspace 专属能力，个人账号无法使用。

Q3：搜索不到某条笔记？keep search是客户端过滤，默认只拉取 500 条。加大--max，或改用list --filter按时间等条件先缩小范围。

Q4：想批量操作多个域用户？对每个用户循环执行--impersonate 用户邮箱即可；配合-j输出汇总结果。

延伸阅读

• Keep 命令索引：gog-keep.md
• 各子命令参考：gog-keep-list.md · gog-keep-create.md · gog-keep-search.md · gog-keep-attachment.md
• 服务账号配置：gog-auth-service-account.md
• Workspace 管理与域范围委托实践：workspace-admin.md
• keep 命令实现源码：internal/cmd/keep.go

掌握gog keep加域范围委托，你就可以在终端里以管理员或自动化脚本的身份，安全、可重复地管理企业 Keep 笔记了 🚀

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli