pp-granola

Granola — Printing Press CLI

由 @dstevens（Damien Stevens）创建。 贡献者： @jeffreydebolt（Jeff DeBolt）、@mvanhorn（Matt Van Horn）、@giuseppebisemi（Giuseppe Bisemi）、@cathrynlavery（Cathryn Lavery）。

前置条件：安装 CLI

此技能通过 granola-pp-cli 二进制文件运行。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。默认情况下，macOS/Linux 上的二进制文件安装到 $HOME/.local/bin，Windows 上安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install granola --cli-only
   

2. 验证：granola-pp-cli --version
3. 确保显示的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/productivity/granola/cmd/granola-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法通过 $PATH 找到二进制文件目录。验证成功前，请勿运行技能命令。

两种数据路径 — 运行任何操作前请先阅读

Granola 桌面应用将数据加密密钥保存在 macOS 数据保护钥匙串组中，该组由绑定到 Granola 自有 Apple Team ID 的授权进行访问控制。任何第三方二进制文件都无法读取该密钥，因此在当前安装版本中，此 CLI 无法读取加密的桌面缓存（cache-v6.json.enc）、SQLCipher 存储 granola.db 和 supabase.json.enc。

但这并不意味着 CLI 无法获取数据。只需运行一次 granola-pp-cli auth login：CLI 会使用自己的会话登录 Granola，并通过 API 同步会议，无需密钥或付费工作区。你只需在浏览器页面上批准一次；此后，每次运行命令时会话都会静默刷新。它绝不会访问 Granola 桌面应用的会话或你的浏览器会话。

以下三种路径会填充本地 SQLite 存储：

路径	填充方式	在当前安装版本中可用？
CLI 自有会话 → 本地存储	auth login，然后运行 sync	**可以。**默认选项。包含会议、标题、时间戳和参会者。
Granola 公共 REST API → 本地存储	sync-api	可以，但需要 GRANOLA_API_KEY，且工作区必须为 Business 或 Enterprise。
桌面加密缓存 → 本地存储	sync	仅适用于迁移前的构建版本，或持有通过 GRANOLA_SAFESTORAGE_KEY_OVERRIDE 提供的迁移前 storage.dek 的机器。其他情况下，sync 会以降级模式运行并报告这一情况。

**读取已同步的数据完全不需要凭据。**所有读取命令都会优先从本地存储读取；仅当存储中没有对应记录，且缓存确实可读时，才会回退到桌面缓存。这两个步骤都不会发起网络请求，也不会查询密钥。只有获取新数据时才需要凭据。

能力划分

在告诉用户数据缺失前，请先阅读本节。在迁移后的安装中，结果为空通常表示“此层级尚未同步”，而不是“你没有任何数据”。

使用 CLI 管理的会话（auth login），并通过 sync 完成数据填充时：

• 会议、标题、时间戳
• 参会者
• 日历事件
• 转录文本（完整片段列表）

转录文本会逐步补齐。由于没有批量转录文本端点，sync 会按会议逐个获取，从最新的会议开始，每次运行最多获取 --transcript-budget（默认值为 250）条。若还有待处理内容，该命令会在 stderr 中提示并记录剩余数量；重新运行 sync 即可继续，或传入 --transcript-budget -1 一次性获取所有剩余内容。对于确实没有录音的会议，只会询问一次，之后便会永久跳过。

回答问题时请注意这一点。 在告诉用户某场会议没有转录文本之前，请先确认补齐过程是否已处理到该会议。sync 会在摘要中报告 transcripts_remaining；非零值表示“尚未获取”，而不是“不存在转录文本”。依赖转录文本的命令（talktime、memo run、attendee brief、collect）在补齐完成前都会缺少数据。

• 配方和面板模板 — recipes list、recipes describe
• 文件夹及文件夹成员 — folder list、folder stream

在同一会话中实时获取，无需同步：

• AI 面板 — panel get，以及 attendee brief 和 folder stream 中的 --panel 内联内容
• 工作区 — workspaces list

这些命令每次调用时都会直接从 API 读取，因此不需要存储记录。代价是，panel get 是唯一完全没有本地回退机制的读取命令：如果会话过期，它会直接失败；而其他命令则会退化为读取已存储的数据。

使用 GRANOLA_API_KEY 并通过 sync-api 完成数据填充时： 公共 API 笔记、生成的摘要、返回的仅所有者可见私密笔记、文件夹成员、发言者归属信息以及完整转录文本。当笔记详情返回 HTTP 413 时，会通过分页转录文本端点获取长篇转录文本。

已冻结但仍可读取 — AI 聊天线程（chat list、chat get）：

聊天是唯一无法继续更新的数据面。Granola 的内部 API 不提供聊天端点（在 7.465.0 版本中于 2026-08-03 探测了 7 种命名方式，均返回 404），因此存储中的线程就是上次桌面缓存同步所捕获的内容，重新同步也不会增加内容。chat list 会在面向用户的输出和 JSON 输出中说明这一点。

根据以上任何数据回答问题前，请先查看 staleness 区块。 当桌面缓存无法读取时，由存储提供的读取结果会附带该区块：refreshable 会告知数据面能否更新，last_catalog_sync_at 记录可更新数据面（如配方）的时间，last_cache_sync_at 记录已冻结数据面（如聊天）的时间。聊天数据可能比其中讨论的会议落后数周 — 请引用日期，不要将其说成最新信息。

在迁移后的安装中，如果用户询问第一组中的某项数据，请说明该数据无法访问。不要根据转录文本内容合成面板、配方结果或聊天线程。

Granola 桌面应用已登录时，为什么还要运行 auth login

因为桌面应用的会话无法共享。它的令牌存放在受权限控制的密钥之后，而桌面应用和浏览器持有的刷新令牌只能使用一次 — 刷新其中一个会将对应的客户端登出。因此，CLI 会维护自己的令牌链，而不是借用其他客户端的令牌。auth login 会将其保存在 CLI 自己的数据目录中，只有你能读取；auth logout 会将其移除。在本地删除它不会撤销上游的令牌。

何时使用此 CLI

当你需要回答 Granola.ai 网页应用和图形界面无法处理的跨会议问题时，请使用 granola-pp-cli，例如参会者时间线、MEMO 流水线状态、配方覆盖缺口、日历叠加以及发言时长汇总。它适用于循环处理转录文本的 Agent、为通话做准备的 CSM，或每周进行复盘的顾问。将默认的 --json 输出与 --select 点分路径搭配使用，可精简 Agent 上下文。

何时不应使用此 CLI

除非用户明确要求，否则不要更改远程状态。远程修改的范围很有限，仅包括 webhooks create / update / delete 和 meetings delete / restore；删除 webhook 需要 --yes。检查、导出、同步、审计读取和离线 webhook 验证都是安全的只读操作。

平台说明

warm <id> <query> 通过 AppleScript 操作 Granola 桌面 GUI，仅适用于 macOS。默认情况下，它会打印将要执行的操作；传入 --launch 才会实际启动应用。在非 macOS 主机上，该命令会以状态码 0 退出，并显示“not supported”消息。其他所有命令均可跨平台使用。

独特功能

这些功能在任何其他用于此 API 的工具中都不可用。

MEMO 流水线

• memo run — 对一个会议，或自某个时间戳以来的所有新会议，运行 preflight → extract 流水线，生成 MEMO 三文件产物和 ndjson 运行状态日志。

  取代驱动 MEMO 流水线的逐会议 shell 循环——一次调用、一个 ndjson 流，且 Agent 可读取。

  granola-pp-cli memo run --since 24h --to ~/Documents/Dev/meeting-transcripts --json
  

• memo queue — 列出所有转录已缓存、但 MEMO 三件套尚未写入磁盘的会议。

  无需用户打开 Granola，即可回答每日问题：“还有哪些会议没做 MEMO？”

  granola-pp-cli memo queue --since 7d --json
  

参会者情报

• attendee timeline — 列出与指定参会者相关的所有会议，按时间从早到晚排序；每行包含标题、日期、文件夹和是否应用了 recipe。

  一条命令即可完成会前准备；展现数月以来与同一人的对话脉络。

  granola-pp-cli attendee timeline [email protected] --since 60d --json --select id,title,started_at,folder,recipes
  

• attendee brief — 提取与某位参会者最近的 N 场会议，并整合其真实缓存笔记和真实 AI 面板摘要——不做综合归纳。

  免去客户负责人每次外部通话前逐个点击会议并复制粘贴的操作。

  granola-pp-cli attendee brief [email protected] --last 3 --panel action-items --json
  

文件夹 + recipe

• folder stream — 以 ndjson 流的形式输出 Granola 文件夹中的所有会议（通过 documentLists + listRules 解析），并内嵌笔记和指定面板内容。

  取代每周回顾时打开文件夹、将每场会议摘要复制粘贴到电子表格中的工作流。

  granola-pp-cli folder stream client-foo --panel summary --json
  

• recipes coverage — 找出指定日期范围内未应用指定面板模板/recipe 的会议。

  每行列出一个遗漏，一目了然地回答周五回顾中的问题：“我是否在每次新潜在客户通话中都运行了 Discovery recipe？”

  granola-pp-cli recipes coverage discovery --since 14d --json
  

转录分析

• talktime — 统计一场会议中各分段来源的发言时长——麦克风（你）与系统（其他所有人），以分钟为单位。

  置信度列可用于评估转录准确性；麦克风与系统的时长对比可用于复盘“我是不是说得太多”。

  granola-pp-cli talktime 196037d9 --json
  

• talktime — 将按来源统计的发言时长汇总扩展到自某日期以来的 N 场会议——了解长期以来谁说得最多。

  可作为时间利用复盘的输入，这是任何逐会议工具都无法生成的。

  granola-pp-cli talktime --by participant --since 7d --json
  

基于缓存的数据

以下两项数据均来自 Granola 桌面应用自身的缓存。chat list 会读取缓存 sync 已同步到本地存储的会话，因此即使在迁移后的安装环境中也能继续提供结果——但无法扩展这一数据集，且输出会说明这一点以及上次同步的时间戳。calendar overlay 会读取由 sync-api 同步的日历事件，因此可以持续使用。

• chat list — 列出并导出与会议关联的 Granola AI 聊天会话（缓存中的 entities.chat_thread + entities.chat_message）。

  恢复用户针对会议积累的 AI 问答记录——在追查几周前你询问过某个客户什么问题时很有用。

  granola-pp-cli chat list 196037d9 --json
  

• calendar overlay — 对 meetingsMetadata 日历事件和 documents.google_calendar_event 执行左反连接，找出已列入日历但未录制的会议。

  Sarah 的周五回顾和 Damien 的“我错过了什么”检查，都可以归结为这一行级差异。

  granola-pp-cli calendar overlay --week 2026-05-11 --missed-only --json
  

直接查询本地存储中的 SQL

本地存储是纯 SQLite 数据库，位于 ~/.local/share/granola-pp-cli/data.db。对于命令无法满足的查询需求，直接查询数据库也是受支持的方式。请先查看架构，不要猜测列名——最常见的两个错误猜测是 meetings.source（实际列名是 row_source）和 folders.name（实际列名是 title）：

# Path, tables, and columns — the contract your SQL runs against.
# Reads the CLI's own store, WAL-current and without writing to it.
granola-pp-cli db schema

# Machine-readable, for scripts
granola-pp-cli db schema --json

# Then query with confidence
sqlite3 ~/.local/share/granola-pp-cli/data.db \
  "select row_source, count(*) from meetings group by row_source;"

主要数据表：meetings、attendees、transcript_segments、folders + folder_memberships、panel_templates、recipes + recipes_usage、chat_threads + chat_messages，以及 sync_state。从 schema v4 起，row_source（= cache|api）也会标记目录表（文件夹、面板模板、食谱）的来源，不再仅限于会议；文件夹还包含 description 和 is_favourited。db schema 提供权威的列表；本段仅用于概述。请将存储视为 SQL 只读——写入应通过 sync 和 sync-api 完成。

流水线规范

• duplicates scan — 对缓存和会议转录文档仓库中的（标题、日期区间、参会者邮箱集合）进行哈希，以便大规模发现重复项。

  会议重新提取时，仓库中会积累近似重复的文件；此命令会返回重复项分组，供清理使用。

  granola-pp-cli duplicates scan --root ~/Documents/Dev/meeting-transcripts --json
  

• tiptap extract — 将 documents[id].notes（TipTap JSON：标题、bullet_list、list_item、粗体标记、段落分隔符）渲染为规范 Markdown，而不是回退到 notes_plain。

  MEMO 摘要文件的质量取决于提取器的保真度；granola.py 会丢失子列表层级和粗体文本。

  granola-pp-cli tiptap extract 196037d9 --as markdown
  

命令参考

此 CLI 提供 35+ 个命令。完整命令树太长，无法直接列出；请通过 CLI 获取规范列表：

granola-pp-cli --help                              # top-level commands
granola-pp-cli <command> --help                    # subcommands + flags
granola-pp-cli agent-context --json                # machine-readable command tree for agents

按分组快速了解：

分组	命令	用途
MEMO 流水线	memo run、memo queue、preflight、extract	组合式三流流水线；读取缓存 + 写入 MEMO 三件套
会议	meetings list、meetings get、meetings fetch-batch、meetings delete、meetings restore、show	列出/检查/修改会议（删除/恢复通过内部 API 修改）
数据流	notes-show、panel get、transcript get、tiptap extract	三种数据流——人工笔记、AI 面板、转录——可分别访问
导出	export、export-all	导出单条或批量的三流合并 Markdown
跨会议分析	attendee timeline、attendee brief、folder stream、recipes coverage、talktime、calendar overlay、stats frequency、stats duration、stats attendees、stats calendar、collect、duplicates scan、chat list、chat get	查询无法通过任何单会议工具回答的问题
文件夹 / 食谱 / 工作区	folders（public-API）、folder list、folder stream、recipes list、recipes describe、recipes coverage、workspaces list	Granola 组织实体
公共 API 镜像	notes list、notes get、folders	使用类型化 Bearer 密钥的端点
公共 API 管理	audit list、webhooks list、webhooks create、webhooks update、webhooks delete、webhooks verify	使用专用密钥读取审计记录；管理 Webhook 生命周期；离线验证投递
同步 / 系统	sync、sync-api、doctor、auth setup、auth status、auth set-token、auth logout、which、agent-context、version、import	本地存储填充（当前安装中，sync-api 是可用路径）、身份验证、能力发现、批量导入
GUI 桥接	warm（仅 macOS）	通过 AppleScript 驱动 Granola 桌面应用

找到合适的命令

当你知道想做什么，但不知道该用哪个命令时，可以直接询问 CLI：

granola-pp-cli which "<capability in your own words>"

which 会将自然语言能力查询映射到此 CLI 精选功能索引中最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help，或缩小查询范围。

使用示例

每日 MEMO 循环

granola-pp-cli memo run --since 24h --to ~/Documents/Dev/meeting-transcripts --json

将昨天以来的每场新会议处理为 MEMO 三元组格式，并仅生成新的产物。

会前参会者简报

granola-pp-cli attendee brief [email protected] --last 3 --panel action-items --json --select meetings.title,meetings.started_at,panels.action_items

提取与 Trevin 最近三场会议中每场的标题、日期和行动事项面板内容。

周五回顾——缺失的使用示例

granola-pp-cli recipes coverage discovery --since 14d --json

列出过去两周内所有未应用 Discovery 面板的新潜在客户通话。省略 slug，即可列出每个面板模板的覆盖缺口。

全仓库重复项清理

granola-pp-cli duplicates scan --root ~/Documents/Dev/meeting-transcripts --json

查找 MEMO 输出仓库中的重复会议集群，以便清理。

日历叠加未录制会议排查

granola-pp-cli calendar overlay --week 2026-05-11 --missed-only --json

检查已加入日历但没有 Granola 录音的会议——每周问责检查。

身份验证设置

1. 获取 API 密钥——仅在获取新数据时需要

可在 Granola 桌面应用 → Settings → Connectors → API keys 中创建 API 密钥。创建密钥需要使用 Business 或 Enterprise Granola 工作区；个人和免费工作区无法签发密钥。共有两种作用域：personal-notes 和 public-notes。请选择能够满足用户实际所需笔记访问权限的最小作用域；如果用户要读取自己的会议笔记，应选择 personal-notes。

将其导出为环境变量：

export GRANOLA_API_KEY="grn_your_key_here"

建议使用环境变量，而不要将密钥持久化到 ~/.config/granola-pp-cli/config.toml。备份和点文件同步工具无法可靠保留文件权限，因此写入配置文件的密钥可能会在同步文件夹中变为所有人可读。

基础 URL 为 https://public-api.granola.ai。列表端点的 page_size 上限为 30，并且只接受 UTC Z 时间戳作为时间筛选条件；CLI 会处理这两点，但如果直接对 API 编写脚本，请务必留意。

审计日志需要单独的 GRANOLA_AUDIT_API_KEY；不要用常规密钥代替。Webhook 创建时只会返回一次 signing_secret。请将其保存为 GRANOLA_WEBHOOK_SECRET，然后在解析或处理捕获的原始请求体前，使用 webhooks verify 进行验证。

使用 audit list --action <prefix> --occurred-after <date> --all 按顺序读取完整时间范围。Webhook 接收端必须根据 event_id 去重：Granola 会使用同一个 ID 重试失败的请求，最长持续四天。已暂停的端点不会接收暂停期间发生的事件，也不会在恢复后补发这些事件。

2. 首次同步数据

运行 granola-pp-cli sync-api。该命令会分页获取笔记列表，然后获取每条笔记的详情及其转录，并将会议、参会者、日历事件、摘要、文件夹成员关系和转录片段写入本地存储——所有读取命令都会查询这些表。后续运行时，可使用 --since 7d 缩小时间范围。

两种同步路径不会互相覆盖。每种路径只会清除自己负责的行，因此按任意顺序对同一存储运行 sync 和 sync-api 都是安全的。

转录还有一项额外保护机制。Granola 会在上游应用转录保留策略，因此较早的会议可能会从 API 返回仅保留少量片段的精简版本，而此存储仍在缓存路径中保留了完整录音。同步绝不会用来自另一来源的较短副本替换现有转录——它会保留已存储的内容、跳过该会议，并在同步摘要中将其报告为 preserved_transcripts，同时输出一行 warning:，列出相关会议。如果某条路径要改写自己此前写入的转录，则不受此限制，无论大小如何变化。

3. 无需密钥即可读取

完成数据填充后，所有读取命令都可离线运行，无需凭据。无论是否设置 GRANOLA_API_KEY，granola-pp-cli transcript get <id> --json 返回的输出都逐字节相同。顶层 source 字段的值为 store（SQLite）、cache（旧版桌面缓存）或 live（公共或内部 API）。

旧版和迁移前的安装

对于密钥迁移前的 Granola 桌面版，顶层 sync 命令仍会读取加密的桌面缓存。首次运行时，系统会提示访问 macOS 钥匙串中的 Granola Safe Storage——点击“始终允许”，后续运行时就不会再提示。

CLI 不会读写桌面应用拥有的任何令牌。它绝不会轮换从 Granola 自己的存储中找到的刷新令牌——supabase.json、supabase.json.enc 或回退使用的 stored-accounts.json——因为这些令牌只能使用一次，轮换令牌会使用户退出 Granola 桌面版。如果请求失败并显示“token expired”，请短暂打开 Granola 桌面版以刷新令牌，然后重新运行。

如果你保留了迁移前的 storage.dek 副本，请将其 32 字节密钥进行 Base64 编码，并设置到 GRANOLA_SAFESTORAGE_KEY_OVERRIDE 中。迁移导入了现有密钥，而不是生成新密钥，因此旧密钥仍可解密今天的文件。

运行 granola-pp-cli doctor，查看此计算机上哪些路径可用。

故障排除

doctor 显示……	处理方法
INFO no Granola install detected	从 granola.ai 安装 Granola 桌面版并登录，或者完全跳过桌面版，改用 API 路径。
INFO not in use (Granola pre-encryption)	加密功能推出前的 Granola 写入的是明文文件；CLI 会直接读取这些文件。
INFO present; run sync to authorize Keychain access	迁移前的安装：运行 granola-pp-cli sync，并在 macOS 提示中点击“始终允许”。
OK ok	已记录上次成功的缓存同步。令牌来源和文档获取数量会显示在 --json 输出中。
ERROR last sync failed to decrypt (key_unavailable)	查看 --json 输出中的 encrypted_store_error 字段。如果其中提到了受权利限制的钥匙串组，这就是上游密钥迁移导致的问题，任何钥匙串授权或重新同步都无法修复——请改用带 API 密钥的 sync-api。只有当消息未提及迁移时，重新登录 Granola 桌面版才是正确的处理方法。
ERROR last sync failed to decrypt (decrypt_failed)	Granola 更新后，加密方案可能发生了变化。请提交问题报告并附上 doctor 输出。
sync-api 成功后读取结果仍为空	查看上文的功能支持范围划分——面板和工作区只能从缓存读取，没有 API 数据源。配方和聊天线程来自最近一次桌面缓存 sync；如果从未运行过该命令，就没有可供提供的数据。

Agent 模式

在任意命令后添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可通过管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留指定字段子集。点分路径可深入嵌套结构；数组会逐项遍历。对于冗长的 API，这对缩小上下文至关重要：

  granola-pp-cli folders --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不会发送

• 离线友好的数据读取 — 通过 sync 或 sync-api 填充数据后，会议和分析数据读取会从 SQLite 提供；审计和 webhook 管理仅支持实时操作

• 非交互式 — 绝不会提示输入，所有输入都通过标志传递

• 大多为只读 — webhooks create / update / delete、meetings delete / restore、import 和 warm --launch 会修改状态；在支持的情况下，删除操作需要明确确认

响应封装

从本地存储或 API 读取的命令会将输出封装在一个来源信息对象中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 以获取数据，并查看 .meta.source 以判断数据是实时获取还是来自本地。只有当 stdout 连接到终端时，才会向 stderr 打印便于阅读的 N results (live) 摘要——通过管道接收输出的客户端或 Agent 会在 stdout 上获得纯 JSON。

自动刷新

每条命令都会先自动刷新本地存储。运行 meetings list、panel get 或其他读取命令前，无需运行 granola-pp-cli sync——CLI 会在每次调用时为你处理。

两个身份验证接口会独立刷新：

接口	执行内容	触发条件
桌面端加密缓存	sync（缓存 → SQLite）	存在 ~/Library/Application Support/Granola/cache-v6.json.enc（或加密前的 cache-v6.json）时
公共 REST API	sync-api（public-api.granola.ai → SQLite）	设置了 GRANOLA_API_KEY，或在配置文件中保存了访问令牌时

两者都可用时，两个刷新流程都会执行（先缓存，再 API）。两者都未配置时，自动刷新会静默跳过，你的底层命令会自行产生身份验证错误。

在迁移后的安装中，缓存流程总会失败——文件存在，因此该流程会触发，并在 stderr 上报告 cache=failed: <migrated-scheme reason>。这是预期行为，并非配置错误。实际执行工作的是 API 流程。无论如何，读取操作都会继续从存储中进行，因为刷新失败不会阻止命令执行。

数据新鲜度上限。 这两个流程都不会促使 Granola 桌面应用从 Granola 服务器拉取数据。缓存流程受限于桌面应用已拉取的数据；API 流程受限于 Granola 服务器已为该笔记发布的数据。如果会议刚结束，请稍等片刻再查看转录。

刷新范围。 API 流程会执行 sync-api 命令的两个阶段——先获取笔记列表，再获取每条笔记的详细信息，以填充 meetings、attendees、transcript_segments 和 folder_memberships——但其范围受到限制，因此可以在每条命令执行前完成：仅获取自上次成功刷新以来变更的一页笔记，而不是整个账户的笔记。在新安装中运行一次 granola-pp-cli sync-api 以回填历史数据；之后自动刷新会保持数据最新。

来源信息行。 当 stderr 是 TTY，且你未处于 --agent / --json / --compact / --quiet 模式时，刷新完成后会在 stderr 上显示一行信息，例如 auto-refresh: cache=ok (1.2s, 47 rows) api=ok (820ms, 12 rows)。Agent 和 JSON 消费方不会在 stdout 上看到任何额外输出。

失败不会阻止命令执行。 刷新失败时，会在 stderr 上输出 cache=failed: <short reason>，随后命令会使用存储中已有的数据继续执行。运行 granola-pp-cli doctor 可排查持续发生的刷新失败。

选择退出（优先级：命令行标志优先于环境变量）：

# Single command:
granola-pp-cli meetings list --no-refresh

# For a shell session / CI job:
export GRANOLA_NO_AUTO_REFRESH=1

# Saved per-profile via the existing profile mechanism:
granola-pp-cli profile save fast --no-refresh
granola-pp-cli --profile fast meetings list

跳过的命令。 以下命令不会触发自动刷新：sync、sync-api、auth*、doctor、help、version、completion、agent-context、profile*、feedback*、which、audit 或 webhooks。这些命令要么不读取会议数据，要么无法在完成身份验证前运行。agent-context --json 会在 auto_refresh.skip_list 下公开完整的跳过列表，供 Agent 查询。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

granola-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
granola-pp-cli feedback --stdin < notes.txt
granola-pp-cli feedback list --json --limit 10

条目会本地存储在 ~/.granola-pp-cli/feedback.jsonl。除非设置了 GRANOLA_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 GRANOLA_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为仅在本地保存。

记录让你感到意外的地方，而不是提交错误报告。简短、具体，写成一行：这些内容会逐渐积累，发挥作用。

输出交付

每条命令都接受 --deliver <sink>。除了（或替代）标准输出外，输出还会发送到指定的接收端，因此 Agent 可以路由命令结果，而无需手动通过管道传递。支持三种接收端：

接收端	效果
stdout	默认；仅写入标准输出
file:<path>	将输出原子写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回包含受支持方案名称的结构化错误。Webhook 失败时会返回非零退出码，并在标准错误中记录 URL + HTTP 状态码。

命名配置

配置是已保存的一组标志值，可在多次调用间重复使用。当计划任务中的 Agent 每次运行都以相同配置调用同一命令时，可以使用配置——这就是 HeyGen 的“Beacon”模式。

granola-pp-cli profile save briefing --json
granola-pp-cli --profile briefing folders
granola-pp-cli profile list --json
granola-pp-cli profile show briefing
granola-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便进行自省的 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	触发速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 granola-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 请参阅上文的先决条件
3. 其他任何内容 → 直接使用（作为带 --agent 的 CLI 命令执行）

安装 MCP 服务

从此 CLI 已发布的公共库条目或预构建版本安装 MCP 二进制文件，然后注册它：

claude mcp add granola-pp-mcp -- granola-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which granola-pp-cli 如果未找到，请提供安装选项（请参阅此技能开头的先决条件）。
2. 将用户查询与上文的独特功能和命令参考中最合适的命令相匹配。
3. 使用 --agent 标志执行：

   granola-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：granola-pp-cli <command> --help。