Back to Details

pp-granola

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- GENERATED FILE — DO NOT EDIT. This file is a verbatim mirror of library/productivity/granola/SKILL.md, regenerated post-merge by tools/generate-skills/. Hand-edits here are silently overwritten on the next regen. Edit the library/ source instead. See AGENTS.md "Generated artifacts: registry.json, cli-skills/". --> <!-- // PATCH(skill-doc-auth-rewrite): Auth Setup section rewritten for the encrypted-cache install flow (Keychain prompt on first sync, no API key, D6 read-only refresh). See library/productivity/granola/.printing-press-patches.json patches[6]. -->
<!-- 【自动生成文件，请勿编辑】 本文件是library/productivity/granola/SKILL.md的精确镜像， 由tools/generate-skills/在合并后重新生成。此处手动编辑的内容会在下次生成时被静默覆盖。请改为编辑library/下的源文件。 详见AGENTS.md中的"Generated artifacts: registry.json, cli-skills/"章节。 --> <!-- // PATCH(skill-doc-auth-rewrite): 身份验证设置章节针对加密缓存安装流程进行了重写（首次同步时弹出钥匙串提示，无需API密钥，D6只读刷新）。详见library/productivity/granola/.printing-press-patches.json中的patches[6]。 -->

Granola — Printing Press CLI

Granola — Printing Press CLI

Prerequisites: Install the CLI

前置条件：安装CLI

This skill drives the 
granola-pp-cli
binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
  1. Install via the Printing Press installer:
    bash
    npx -y @mvanhorn/printing-press install granola --cli-only
  2. Verify: 
    granola-pp-cli --version
  3. Ensure 
    $GOPATH/bin
    (or 
    $HOME/go/bin
    ) is on 
    $PATH
    .
If the 
npx
install fails before this CLI has a public-library category, install Node or use the category-specific Go fallback after publish.
If 
--version
reports "command not found" after install, the install step did not put the binary on 
$PATH
. Do not proceed with skill commands until verification succeeds.
This CLI reads Granola’s local cache directly and adds the queries Granola.ai’s web app and existing community CLIs cannot answer. Cache-first, then internal API, then public API — transparent fallthrough. memo run, memo queue, attendee timeline, recipes coverage, calendar overlay, and talktime are local-data joins no per-meeting tool produces. Works offline; agent-native JSON by default.
本技能基于
granola-pp-cli
二进制文件运行。在调用本技能的任何命令之前，必须先验证CLI已安装。如果未安装，请先执行以下步骤：
  1. 通过Printing Press安装器安装：
    bash
    npx -y @mvanhorn/printing-press install granola --cli-only
  2. 验证：
    granola-pp-cli --version
  3. 确保
    $GOPATH/bin
    （或
    $HOME/go/bin
    ）已添加到
    $PATH
    环境变量中。
如果在该CLI进入公共库分类之前
npx
安装失败，请安装Node.js，或在发布后使用特定分类的Go语言备选安装方式。
如果安装后执行
--version
提示“command not found”，说明安装步骤未将二进制文件添加到
$PATH
中。在验证成功之前，请不要继续使用技能命令。
该CLI直接读取Granola的本地缓存，并新增了Granola.ai网页应用和现有社区CLI无法回答的查询功能。采用缓存优先、内部API次之、公共API最后的透明降级策略。memo运行、memo队列、参会者时间线、模板覆盖情况、日历叠加层以及发言时长统计等功能，都是单会议工具无法实现的本地数据关联操作。支持离线使用；默认输出Agent原生JSON格式。

When to Use This CLI

何时使用此CLI

Reach for granola-pp-cli when you need to answer cross-meeting questions Granola.ai’s web app and the GUI cannot — attendee timelines, MEMO pipeline state, recipes coverage gaps, calendar overlay, talk-time aggregation. It is the right tool for an agent processing transcripts in a loop, a CSM doing pre-call prep, or a consultant running a weekly retro. Pair the --json default with --select dotted paths to keep agent context lean.
当你需要回答Granola.ai网页应用和GUI无法解决的跨会议问题时——比如参会者时间线、MEMO管道状态、模板覆盖缺口、日历叠加层、发言时长汇总——请使用granola-pp-cli。它非常适合循环处理转录内容的Agent、进行会前准备的客户成功经理（CSM），或是开展每周回顾的顾问。将默认的--json参数与--select点路径参数配合使用，可精简Agent的上下文信息。

When Not to Use This CLI

何时不使用此CLI

Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis.
请勿针对需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或修改远程状态的请求激活此CLI。本CLI仅提供用于查看、导出、同步和分析的只读命令。

Platform Notes

平台说明

warm <id> <query>
drives the Granola desktop GUI via AppleScript and is macOS-only. It prints what it would do by default; pass 
--launch
to actually activate the app. On non-macOS hosts the command exits 0 with a "not supported" message. All other commands are cross-platform.
warm <id> <query>
命令通过AppleScript驱动Granola桌面GUI，仅支持macOS系统。默认情况下它会打印将要执行的操作；传递
--launch
参数可实际激活应用。在非macOS主机上执行该命令会返回退出码0，并显示“不支持”的提示信息。所有其他命令均支持跨平台。

Unique Capabilities

独特功能

These capabilities aren't available in any other tool for this API.
这些功能是其他同类型API工具所不具备的。

MEMO pipeline

MEMO管道

  • memo run
     — Run the preflight → extract pipeline on one meeting or every new meeting since a timestamp, emitting the MEMO three-file artifact and an ndjson run-state ledger.
    Replaces the per-meeting shell loop that drives the MEMO pipeline — one call, one ndjson stream, agent-readable.
    bash
    granola-pp-cli memo run --since 24h --to ~/Documents/Dev/meeting-transcripts --json
  • memo queue
     — List every meeting whose transcript is in the cache but whose MEMO triple is not yet on disk.
    Answers the daily question “what’s still un-MEMO’d?” without the user opening Granola at all.
    bash
    granola-pp-cli memo queue --since 7d --json
  • memo run
     — 对单个会议或某个时间点以来的所有新会议执行预检查→提取管道流程，生成MEMO三文件工件和ndjson运行状态日志。
    替代驱动MEMO管道的单会议Shell循环——一次调用，一个ndjson流，Agent可直接读取。
    bash
    granola-pp-cli memo run --since 24h --to ~/Documents/Dev/meeting-transcripts --json
  • memo queue
     — 列出所有转录内容已在缓存中但MEMO三元组尚未保存到磁盘的会议。
    无需打开Granola即可回答日常问题“还有哪些会议未生成MEMO？”。
    bash
    granola-pp-cli memo queue --since 7d --json

Attendee intelligence

参会者智能分析

  • attendee timeline
     — Every meeting with a given attendee, ordered oldest→newest, with title, date, folder, and recipe-applied flag per row.
    Pre-call prep in one command; surfaces the conversation arc with a single person across months of meetings.
    bash
    granola-pp-cli attendee timeline alice@example.com --since 60d --json --select id,title,started_at,folder,recipes
  • attendee brief
     — Pulls the last N meetings with an attendee and stitches together their real cached notes plus real AI panel summaries — no synthesis.
    Eliminates the click-each-meeting copy-paste that account leads do before every external call.
    bash
    granola-pp-cli attendee brief alice@example.com --last 3 --panel action-items --json
  • attendee timeline
     — 列出与指定参会者相关的所有会议，按时间从旧到新排序，每行包含会议标题、日期、文件夹和模板应用标记。
    一条命令完成会前准备；展示与某个人数月来的对话脉络。
    bash
    granola-pp-cli attendee timeline alice@example.com --since 60d --json --select id,title,started_at,folder,recipes
  • attendee brief
     — 获取与参会者相关的最近N次会议内容，拼接真实的缓存笔记和AI面板摘要——无需重新合成。
    消除客户主管在每次外部会议前逐个点击会议复制粘贴的操作。
    bash
    granola-pp-cli attendee brief alice@example.com --last 3 --panel action-items --json

Folders + recipes

文件夹与模板

  • folder stream
     — ndjson stream of every meeting in a Granola folder (resolved via documentLists + listRules) with notes and a named panel inlined.
    Replaces the weekly retro workflow of opening a folder and copy-pasting each meeting’s summary into a spreadsheet.
    bash
    granola-pp-cli folder stream client-foo --panel summary --json
  • recipes coverage
     — Surface meetings that did NOT have a named panel template/recipe applied within a date range.
    Friday retro question “did I run the Discovery recipe on every new-prospect call?” answered in one row per gap.
    bash
    granola-pp-cli recipes coverage discovery --since 14d --json
  • folder stream
     — 以ndjson流形式输出Granola文件夹中的所有会议（通过documentLists + listRules解析），并内嵌笔记和指定面板内容。
    替代每周回顾时打开文件夹并将每个会议摘要复制粘贴到电子表格的工作流程。
    bash
    granola-pp-cli folder stream client-foo --panel summary --json
  • recipes coverage
     — 展示在指定日期范围内未应用指定面板模板/配方的会议。
    一键回答周五回顾时的问题“我是否在所有新潜在客户会议中运行了Discovery模板？”，每条记录对应一个缺口。
    bash
    granola-pp-cli recipes coverage discovery --since 14d --json

Transcript analytics

转录分析

  • talktime
     — Per-segment-source talk-time for one meeting — microphone (you) vs system (everyone else) in minutes.
    Confidence column lets you grade transcript accuracy; mic vs system split is the input to “am I talking too much” retros.
    bash
    granola-pp-cli talktime 196037d9 --json
  • talktime
     — Lifts the per-source talk-time aggregation across N meetings since a date — who-talked-most over time.
    Time-defrag retro input that no per-meeting tool can produce.
    bash
    granola-pp-cli talktime --by participant --since 7d --json
  • talktime
     — 单个会议的分段发言时长统计——麦克风（你）与系统（其他人）的发言时长（分钟）。
    置信度列可用于评估转录准确性；麦克风与系统的发言占比是“我是否说得太多”回顾分析的输入数据。
    bash
    granola-pp-cli talktime 196037d9 --json
  • talktime
     — 汇总指定日期以来N次会议的各参会者发言时长——统计一段时间内谁发言最多。
    这是单会议工具无法提供的时间碎片整理回顾输入数据。
    bash
    granola-pp-cli talktime --by participant --since 7d --json

Cache-native data

缓存原生数据

  • chat list
     — List and dump Granola’s AI chat threads anchored to a meeting (entities.chat_thread + entities.chat_message in the cache).
    Recovers the AI Q&A history a user has accumulated against a meeting — useful when chasing what you asked about an account weeks ago.
    bash
    granola-pp-cli chat list 196037d9 --json
  • calendar overlay
     — Left-anti-join meetingsMetadata calendar events with documents.google_calendar_event to find calendared-but-not-recorded meetings.
    Sarah’s Friday retro and Damien’s “what did I miss” sweep both reduce to this row-level diff.
    bash
    granola-pp-cli calendar overlay --week 2026-05-11 --missed-only --json
  • chat list
     — 列出并导出Granola中锚定到某会议的AI聊天线程（缓存中的entities.chat_thread + entities.chat_message）。
    恢复用户针对某会议积累的AI问答历史——在追查数周前针对某个客户的问题时非常有用。
    bash
    granola-pp-cli chat list 196037d9 --json
  • calendar overlay
     — 通过左反连接meetingsMetadata日历事件与documents.google_calendar_event，找出已安排但未录制的会议。
    Sarah的周五回顾和Damien的“我错过了什么”排查都可以简化为这个行级差异分析。
    bash
    granola-pp-cli calendar overlay --week 2026-05-11 --missed-only --json

Pipeline hygiene

管道卫生

  • duplicates scan
     — Hash (title, date-bucket, attendee-email-set) across the cache and a meeting-transcripts repo to surface duplicates at scale.
    Repos accumulate near-duplicate files when meetings are re-extracted; this returns the dupe groups for cleanup.
    bash
    granola-pp-cli duplicates scan --root ~/Documents/Dev/meeting-transcripts --json
  • tiptap extract
     — Render documents[id].notes (TipTap JSON: headings, bullet_list, list_item, bold marks, paragraph_break) to canonical markdown instead of falling back to notes_plain.
    The MEMO summary file’s quality is bounded by extractor fidelity; granola.py loses sub-list hierarchy and bold runs.
    bash
    granola-pp-cli tiptap extract 196037d9 --as markdown
  • duplicates scan
     — 对缓存和会议转录仓库中的（标题、日期桶、参会者邮箱集合）进行哈希运算，大规模识别重复内容。
    当会议被重新提取时，仓库会积累近重复文件；此命令返回重复组以便清理。
    bash
    granola-pp-cli duplicates scan --root ~/Documents/Dev/meeting-transcripts --json
  • tiptap extract
     — 将documents[id].notes（TipTap JSON格式：标题、项目符号列表、列表项、粗体标记、段落换行）渲染为标准markdown格式，而非回退到notes_plain纯文本。
    MEMO摘要文件的质量取决于提取器的保真度；granola.py会丢失子列表层级和粗体格式。
    bash
    granola-pp-cli tiptap extract 196037d9 --as markdown

Command Reference

命令参考

This CLI exposes 35+ commands. The full tree is too long to inline; ask the CLI for the canonical list:
bash
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
Quick orientation by group:
GroupCommandsPurpose
MEMO pipeline
memo run
, 
memo queue
, 
preflight
, 
extract
Composed three-stream pipeline; reads cache + writes MEMO triple
Meetings
meetings list
, 
meetings get
, 
meetings fetch-batch
, 
meetings delete
, 
meetings restore
, 
show
List/inspect/mutate meetings (delete/restore mutate via internal API)
Streams
notes-show
, 
panel get
, 
transcript get
, 
tiptap extract
The three streams — human notes, AI panels, transcript — addressable separately
Export
export
, 
export-all
Combined three-stream markdown export, single or bulk
Cross-meeting analytics
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
Queries no per-meeting tool can answer
Folders / recipes / workspaces
folders
(public-API), 
folder list
, 
folder stream
, 
recipes list
, 
recipes describe
, 
recipes coverage
, 
workspaces list
Granola organizational entities
Public-API mirrors
notes list
, 
notes get
, 
folders
Typed Bearer-key endpoints
Sync / system
sync
, 
sync-api
, 
doctor
, 
auth login
, 
auth status
, 
auth set-token
, 
auth logout
, 
which
, 
agent-context
, 
version
, 
import
Local store hydration, auth, capability discovery, batch import
GUI bridge
warm
(macOS only)		Drives Granola desktop app via AppleScript
该CLI提供35+条命令。完整命令树过长，无法内联展示；请直接向CLI查询标准命令列表：
bash
granola-pp-cli --help                              # 顶级命令
granola-pp-cli <command> --help                    # 子命令及参数
granola-pp-cli agent-context --json                # 供Agent使用的机器可读命令树
按分组快速了解：
分组命令用途
MEMO管道
memo run
, 
memo queue
, 
preflight
, 
extract
组合式三流管道；读取缓存并写入MEMO三元组
会议管理
meetings list
, 
meetings get
, 
meetings fetch-batch
, 
meetings delete
, 
meetings restore
, 
show
列出/查看/修改会议（delete/restore通过内部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
（公共API）, 
folder list
, 
folder stream
, 
recipes list
, 
recipes describe
, 
recipes coverage
, 
workspaces list
Granola的组织实体
公共API镜像
notes list
, 
notes get
, 
folders
带类型的Bearer密钥端点
同步/系统
sync
, 
sync-api
, 
doctor
, 
auth login
, 
auth status
, 
auth set-token
, 
auth logout
, 
which
, 
agent-context
, 
version
, 
import
本地存储同步、身份验证、功能发现、批量导入
GUI桥接
warm
（仅macOS）		通过AppleScript驱动Granola桌面应用

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:
bash
granola-pp-cli which "<capability in your own words>"
which
resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 
0
means at least one match; exit code 
2
means no confident match — fall back to 
--help
or use a narrower query.
当你知道要做什么但不知道对应命令时，请直接询问CLI：
bash
granola-pp-cli which "<用你自己的语言描述功能>"
which
命令会将自然语言功能查询解析为该CLI精选功能索引中最匹配的命令。退出码
0
表示至少找到一个匹配项；退出码
2
表示没有确定的匹配项——请回退到
--help
或使用更精确的查询。

Recipes

常用示例

Daily MEMO loop

每日MEMO循环

bash
granola-pp-cli memo run --since 24h --to ~/Documents/Dev/meeting-transcripts --json
Process every new meeting since yesterday into the MEMO triple format and yield only the new artifacts.
bash
granola-pp-cli memo run --since 24h --to ~/Documents/Dev/meeting-transcripts --json
处理自昨天以来的所有新会议，生成MEMO三元组格式，并仅返回新生成的工件。

Pre-call attendee brief

会前参会者简报

bash
granola-pp-cli attendee brief alice@example.com --last 3 --panel action-items --json --select meetings.title,meetings.started_at,panels.action_items
Pull the last three meetings with Trevin and only the title, date, and action-items panel content per meeting.
bash
granola-pp-cli attendee brief alice@example.com --last 3 --panel action-items --json --select meetings.title,meetings.started_at,panels.action_items
获取与Trevin相关的最近三次会议内容，仅返回每次会议的标题、日期和行动项面板内容。

Friday retro — missing recipes

周五回顾——遗漏的模板

bash
granola-pp-cli recipes coverage discovery --since 14d --json
Surface every new-prospect call in the last fortnight that did not have the Discovery panel applied. Omit the slug to list coverage gaps across every panel template.
bash
granola-pp-cli recipes coverage discovery --since 14d --json
展示过去两周内所有未应用Discovery面板的新潜在客户会议。省略slug参数可列出所有面板模板的覆盖缺口。

Repo-wide duplicate scrub

仓库范围重复内容清理

bash
granola-pp-cli duplicates scan --root ~/Documents/Dev/meeting-transcripts --json
Find duplicate-meeting clusters across the MEMO output repo for cleanup.
bash
granola-pp-cli duplicates scan --root ~/Documents/Dev/meeting-transcripts --json
在MEMO输出仓库中查找重复会议集群以便清理。

Calendar-overlay missed-meeting sweep

日历叠加层——遗漏会议排查

bash
granola-pp-cli calendar overlay --week 2026-05-11 --missed-only --json
Calendared meetings with no Granola recording — weekly accountability check.
bash
granola-pp-cli calendar overlay --week 2026-05-11 --missed-only --json
查找已安排但未被Granola录制的会议——每周问责检查。

Auth Setup

身份验证设置

  1. Install Granola desktop and sign in. The CLI reads the local cache and tokens the desktop manages. No CLI-side credentials to configure.
  2. Run any command. On macOS, the first invocation that needs the cache or tokens (typically 
    granola-pp-cli sync
    ) triggers a Keychain prompt for 
    Granola Safe Storage
    . Click "Always Allow" so subsequent runs are silent. The CLI uses Granola's own Keychain-stored encryption key to decrypt 
    cache-v6.json.enc
    and 
    supabase.json.enc
    .
  3. CLI is read-only against the refresh token. Granola desktop owns rotation; the CLI never calls 
    RefreshAccessToken
    against the encrypted token store because rotating it there would sign Granola desktop out next time the desktop tries to refresh. If a request fails with "token expired", open Granola desktop briefly to refresh, then re-run the CLI command.
  4. Power users / CI: 
    GRANOLA_WORKOS_TOKEN
    .     Setting this env var bypasses the Keychain prompt entirely and accepts the refresh-rotation trade-off (rotating the token via the CLI will sign the desktop out). Use only when CLI-side refresh is required, typically for headless agents.
Optional public REST API path: set 
GRANOLA_API_KEY
for the typed 
notes
and 
folders
top-level commands at 
public-api.granola.ai
. Most workflows do not need this.
Run 
granola-pp-cli doctor
to verify setup. The "Encrypted store" line distinguishes four states: not installed, pre-encryption Granola, present-but-not-yet-synced, ok, or last-sync-failed-with-class.
  1. 安装Granola桌面应用并登录。CLI读取由桌面应用管理的本地缓存和令牌。无需在CLI端配置凭据。
  2. 运行任意命令。在macOS上，首次需要访问缓存或令牌的调用（通常是
    granola-pp-cli sync
    ）会触发“Granola Safe Storage”的钥匙串提示。点击“始终允许”，以便后续运行无需再提示。CLI使用Granola自身存储在钥匙串中的加密密钥来解密
    cache-v6.json.enc
    和
    supabase.json.enc
    。
  3. CLI对刷新令牌具有只读权限。Granola桌面应用负责令牌轮换；CLI绝不会针对加密令牌存储调用
    RefreshAccessToken
    ，因为在此处轮换令牌会导致Granola桌面应用下次尝试刷新时退出登录。如果请求因“令牌过期”失败，请短暂打开Granola桌面应用进行刷新，然后重新运行CLI命令。
  4. 高级用户/CI环境：
    GRANOLA_WORKOS_TOKEN
    。设置此环境变量可完全绕过钥匙串提示，但需接受令牌轮换的权衡（通过CLI轮换令牌会导致桌面应用退出登录）。仅当需要CLI端刷新时使用，通常用于无头Agent。
可选公共REST API路径：为
public-api.granola.ai
的顶级
notes
和
folders
命令设置
GRANOLA_API_KEY
。大多数工作流程不需要此设置。
运行
granola-pp-cli doctor
验证设置。“Encrypted store”行显示四种状态：未安装、加密前版本的Granola、已存在但未同步、正常，或上次同步失败及错误类型。

Troubleshooting

故障排除

doctor
says...		What to do
INFO no Granola install detected
Install Granola desktop from granola.ai and sign in.
INFO not in use (Granola pre-encryption)
Granola desktop pre-encryption versions wrote plaintext files; the CLI still reads them. Upgrade Granola desktop to pick up the encrypted store.
INFO present; run sync to authorize Keychain access
Run 
granola-pp-cli sync
. Click "Always Allow" on the macOS prompt.
OK ok
Last successful sync recorded. Token source and document-fetch count visible in 
--json
output.
ERROR last sync failed to decrypt (key_unavailable)
Sign back into Granola desktop, re-run sync, accept the Keychain prompt.
ERROR last sync failed to decrypt (decrypt_failed)
Encryption scheme may have drifted with a Granola update. File an issue with the doctor output.
doctor
提示...		解决方法
INFO no Granola install detected
从granola.ai安装Granola桌面应用并登录。
INFO not in use (Granola pre-encryption)
Granola桌面应用的加密前版本会写入明文文件；CLI仍可读取它们。请升级Granola桌面应用以使用加密存储。
INFO present; run sync to authorize Keychain access
运行
granola-pp-cli sync
，在macOS提示中点击“始终允许”。
OK ok
记录了上次成功同步。
--json
输出中可见令牌来源和文档获取数量。
ERROR last sync failed to decrypt (key_unavailable)
重新登录Granola桌面应用，重新运行sync命令，接受钥匙串提示。
ERROR last sync failed to decrypt (decrypt_failed)
加密方案可能因Granola更新而变更。请提交包含doctor输出的问题报告。

Agent Mode

Agent模式

Add 
--agent
to any command. Expands to: 
--json --compact --no-input --no-color --yes
.
  • Pipeable — JSON on stdout, errors on stderr
  • Filterable — 
    --select
    keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
    bash
    granola-pp-cli folders --agent --select id,name,status
  • Previewable — 
    --dry-run
    shows the request without sending
  • Offline-friendly — 
    sync
    and the 
    meetings list --query <text>
    FTS path use the local SQLite store
  • Non-interactive — never prompts, every input is a flag
  • Mostly read-only — 
    meetings delete
    , 
    meetings restore
    , 
    import
    , and 
    warm --launch
    are the only commands that mutate state; every other command inspects, exports, syncs, or analyzes
在任意命令后添加
--agent
参数。等效于：
--json --compact --no-input --no-color --yes
。
  • 可管道化 — stdout输出JSON，stderr输出错误信息
  • 可过滤 — 
    --select
    参数保留字段子集。点路径可深入嵌套结构；数组可遍历每个元素。对于冗长API，这是精简上下文的关键：
    bash
    granola-pp-cli folders --agent --select id,name,status
  • 可预览 — 
    --dry-run
    参数显示请求但不发送
  • 离线友好 — 
    sync
    和
    meetings list --query <text>
    全文检索路径使用本地SQLite存储
  • 非交互式 — 从不弹出提示，所有输入均通过参数传递
  • 基本只读 — 
    meetings delete
    、
    meetings restore
    、
    import
    和
    warm --launch
    是仅有的修改状态命令；所有其他命令均用于查看、导出、同步或分析

Response envelope

响应信封

Commands that read from the local store or the API wrap output in a provenance envelope:
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}
Parse 
.results
for data and 
.meta.source
to know whether it's live or local. A human-readable 
N results (live)
summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
从本地存储或API读取数据的命令会将输出包裹在来源信封中：
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}
解析
.results
获取数据，
.meta.source
可判断数据是实时还是本地来源。当stdout是终端时，会向stderr打印类似
N results (live)
的人类可读摘要；管道/Agent消费者仅会在stdout获取纯JSON。

Auto-Refresh

自动刷新

Every command auto-refreshes the local store as its first action. You do not need to run 
granola-pp-cli sync
before 
meetings list
, 
panel get
, or any other read — the CLI handles that for you on every invocation.
Two auth surfaces refresh independently:
SurfaceWhat runsWhen it fires
Desktop encrypted cache
sync
(cache → SQLite)		When 
~/Library/Application Support/Granola/cache-v6.json.enc
(or pre-encryption 
cache-v6.json
) is present
Public REST API
sync-api
(public-api.granola.ai → SQLite)		When 
GRANOLA_API_KEY
is set or an access token is saved in the config file
When both are available, both refresh routines fire (cache first, then api). When neither is configured, auto-refresh is a silent no-op and your underlying command produces its own auth error.
Freshness ceiling. Auto-refresh reads from Granola desktop's encrypted cache file; it does not poke the desktop app to refresh from Granola servers. The freshness ceiling is whatever Granola desktop has already pulled. If a meeting just ended and the desktop hasn't synced from servers yet, no CLI-side refresh will surface it. For latest-second-fresh data, open Granola desktop briefly before invoking the CLI.
Provenance line. When stderr is a TTY and you are not in 
--agent
/ 
--json
/ 
--compact
/ 
--quiet
mode, a one-liner like 
auto-refresh: cache=ok (1.2s, 47 rows)  api=ok (820ms, 12 rows)
lands on stderr after the refresh. Agent and JSON consumers see no chatter on stdout.
Failures are non-fatal. A refresh that fails prints 
cache=failed: <short reason>
on stderr and the command proceeds against whatever data is already in the store. Run 
granola-pp-cli doctor
to investigate persistent refresh failures.
Opt out (precedence: flag wins over env):
bash
undefined
每个命令都会将自动刷新本地存储作为第一个操作。你无需在运行
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）。当两者都未配置时，自动刷新会静默无操作，后续命令会自行产生身份验证错误。
新鲜度上限。自动刷新读取Granola桌面应用的加密缓存文件；它不会触发桌面应用从Granola服务器刷新数据。新鲜度上限取决于Granola桌面应用已拉取的数据。如果会议刚刚结束且桌面应用尚未从服务器同步，CLI端的刷新无法获取到该会议数据。如需最新数据，请在调用CLI前短暂打开Granola桌面应用。
来源信息行。当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: <简短原因>
，命令会继续使用存储中已有的数据运行。如果刷新持续失败，请运行
granola-pp-cli doctor
进行排查。
退出自动刷新（优先级：参数高于环境变量）：
bash
undefined

Single command:

单个命令：

granola-pp-cli meetings list --no-refresh
granola-pp-cli meetings list --no-refresh

For a shell session / CI job:

Shell会话/CI作业：

export GRANOLA_NO_AUTO_REFRESH=1
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

**Skipped commands.** Auto-refresh never fires for `sync`, `sync-api`, `auth*`, `doctor`, `help`, `version`, `completion`, `agent-context`, `profile*`, `feedback*`, or `which`. These either do not read data or cannot operate before auth is established. `agent-context --json` exposes the full skip list under `auto_refresh.skip_list` for introspecting agents.
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`命令中触发。这些命令要么不读取数据，要么无法在身份验证建立前运行。`agent-context --json`会在`auto_refresh.skip_list`下暴露完整的跳过列表，供Agent进行自省。

Agent Feedback

Agent反馈

When you (or the agent) notice something off about this CLI, record it:
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
Entries are stored locally at 
~/.granola-pp-cli/feedback.jsonl
. They are never POSTed unless 
GRANOLA_FEEDBACK_ENDPOINT
is set AND either 
--send
is passed or 
GRANOLA_FEEDBACK_AUTO_SEND=true
. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
当你（或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
时，才会发送反馈。默认行为是仅本地存储。
请记录让你感到意外的内容，而非正式的错误报告。简短、具体、一句话即可：这样的反馈价值最大。

Output Delivery

输出交付

Every command accepts 
--deliver <sink>
. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
SinkEffect
stdout
Default; write to stdout only
file:<path>
Atomically write output to 
<path>
(tmp + rename)
webhook:<url>
POST the output body to the URL (
application/json
or 
application/x-ndjson
when 
--compact
)
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
每个命令都支持
--deliver <sink>
参数。输出会发送到指定的接收端，同时（或替代）输出到stdout，以便Agent无需手动管道即可路由命令结果。支持三种接收端：
接收端效果
stdout
默认值；仅输出到stdout
file:<path>
原子性地将输出写入
<path>
（先写入临时文件再重命名）
webhook:<url>
将输出体POST到指定URL（当使用
--compact
时为
application/json
或
application/x-ndjson
格式）
不支持的协议会返回结构化错误，并列出支持的协议集。Webhook失败会返回非零退出码，并向stderr记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
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
Explicit flags always win over profile values; profile values win over defaults. 
agent-context
lists all available profiles under 
available_profiles
so introspecting agents discover them at runtime.
配置文件是一组保存的参数值，可在多次调用中复用。当定时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在运行时发现。

Exit Codes

退出码

CodeMeaning
0Success
2Usage error (wrong arguments)
3Resource not found
4Authentication required
5API error (upstream issue)
7Rate limited (wait and retry)
10Config error
代码含义
0成功
2使用错误（参数错误）
3资源未找到
4需要身份验证
5API错误（上游问题）
7速率限制（请等待后重试）
10配置错误

Argument Parsing

参数解析

Parse 
$ARGUMENTS
:
  1. Empty, 
    help
    , or 
    --help
     → show 
    granola-pp-cli --help
    output
  2. Starts with 
    install
     → ends with 
    mcp
    → MCP installation; otherwise → see Prerequisites above
  3. Anything else → Direct Use (execute as CLI command with 
    --agent
    )
解析
$ARGUMENTS
的逻辑：
  1. 为空、
    help
    或
    --help
     → 显示
    granola-pp-cli --help
    输出
  2. 以
    install
    开头     → 以
    mcp
    结尾 → MCP安装；否则 → 参见顶部的前置条件
  3. 其他情况 → 直接使用（以
    --agent
    参数执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:
bash
claude mcp add granola-pp-mcp -- granola-pp-mcp
Verify: 
claude mcp list
从该CLI的已发布公共库条目或预构建版本安装MCP二进制文件，然后注册：
bash
claude mcp add granola-pp-mcp -- granola-pp-mcp
验证：
claude mcp list

Direct Use

直接使用

  1. Check if installed: 
    which granola-pp-cli
    If not found, offer to install (see Prerequisites at the top of this skill).
  2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
  3. Execute with the 
    --agent
    flag:
    bash
    granola-pp-cli <command> [subcommand] [args] --agent
  4. If ambiguous, drill into subcommand help: 
    granola-pp-cli <command> --help
    .
  1. 检查是否已安装：
    which granola-pp-cli
    如果未找到，提供安装选项（参见顶部的前置条件）。
  2. 将用户查询与上述独特功能和命令参考中的最佳匹配命令进行匹配。
  3. 带
    --agent
    参数执行：
    bash
    granola-pp-cli <command> [subcommand] [args] --agent
  4. 如果存在歧义，查看子命令帮助：
    granola-pp-cli <command> --help
    。