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 命令都支持这两个核心参数：

参数	作用
`--service-account`	服务账号 JSON 密钥文件路径
`--impersonate`	要代理的域内用户邮箱（与 service-account 配合使用）

例如以域内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，再用此命令落盘。

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

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

参数	说明
`-n`/`--dry-run`	只打印将执行的动作，不发起变更请求
`--readonly`	运行时拦截所有写操作（delete、create 会直接失败）
`-j`/`--json`	输出 JSON，最适合脚本与 AI 代理
`--no-input`	永不交互提问，出错即失败，适合 CI
`--wrap-untrusted`	将拉取的文本包裹为"不可信内容"标记，防止提示注入