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. このスキルを実行するエージェント／ランタイムから、報告されたインストール先ディレクトリに $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 が通っていません。確認が成功するまで、スキルのコマンドを実行しないでください。

2 つのデータ経路 — 実行前にお読みください

Granola デスクトップは、Granola 独自の Apple Team ID にひも付いたエンタイトルメントによってアクセスが制限される macOS のデータ保護キーチェーン・グループに、データ暗号化キーを保存しています。サードパーティ製のバイナリはこのキーを読み取れないため、暗号化されたデスクトップキャッシュ（cache-v6.json.enc）、SQLCipher ストアの granola.db、supabase.json.enc は、現在のインストール環境ではすべてこの CLI から読み取れません。

ただし、CLI でデータを利用できないわけではありません。granola-pp-cli auth login を一度実行すると、CLI は独自のセッションで Granola にサインインし、キーも有料ワークスペースも必要とせず、API 経由でミーティングを同期します。ブラウザーで 1 ページを承認すれば、その後は各コマンドの実行時にセッションが自動で更新されます。Granola デスクトップアプリのセッションにも、ブラウザーのセッションにも触れません。

ローカルの SQLite ストアにデータを取り込む経路は 3 つあります。

経路	データの取り込み方法	現在のインストール環境で利用できますか？
CLI 独自のセッション → ローカルストア	auth login の後に sync	はい。 既定の方法です。ミーティング、タイトル、タイムスタンプ、参加者を取得します。
Granola 公開 REST API → ローカルストア	sync-api	はい。ただし、Business または Enterprise ワークスペースが必要な GRANOLA_API_KEY が必要です。
デスクトップの暗号化キャッシュ → ローカルストア	sync	移行前のビルドの場合、または GRANOLA_SAFESTORAGE_KEY_OVERRIDE を通じて提供された移行前の storage.dek を保持するマシンでのみ利用できます。 それ以外の場合、sync は機能を縮小して実行され、その旨を報告します。

すでに同期済みのデータを読み取るために、認証情報は必要ありません。 すべての読み取りコマンドは、まずローカルストアからデータを取得し、ストアに該当する行がなく、キャッシュを実際に読み取れる場合に限ってデスクトップキャッシュにフォールバックします。どちらの手順でもネットワークへの接続やキーの参照は行いません。認証情報が必要なのは、新しいデータを取得するときだけです。

機能の分担

ユーザーにデータが見つからないと伝える前に、これを読んでください。移行済みのインストールで結果が空の場合、通常は「この階層では同期されていない」という意味であり、「データが存在しない」という意味ではありません。

auth login で CLI が所有するセッションを使い、sync でデータを取り込む場合：

• ミーティング、タイトル、タイムスタンプ
• 参加者
• カレンダーイベント
• トランスクリプト（全セグメントのリスト）

トランスクリプトは段階的にバックフィルされます。一括取得用のトランスクリプトエンドポイントはないため、sync はミーティングごとに新しい順で取得し、1 回の実行につき最大 --transcript-budget（デフォルトは 250）件を処理します。未処理のデータが残っている場合、コマンドはその旨を stderr に出力し、残り件数を記録します。sync を再実行して続きを取得するか、--transcript-budget -1 を指定して残りすべてを一度に取得してください。録音が実際に存在しないミーティングについては、一度だけ確認し、その後は永久にスキップします。

質問に回答する際は、この点が重要です。 ユーザーにミーティングのトランスクリプトがないと伝える前に、バックフィルがそのミーティングまで完了しているか確認してください。sync はサマリーに transcripts_remaining を表示します。値が 0 以外の場合は「まだ取得されていない」という意味であり、「トランスクリプトが存在しない」という意味ではありません。トランスクリプトに依存するコマンド（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 はローカルのフォールバックが一切ない唯一の読み取りコマンドです。セッションが切れると、ほかのすべてが保存済みデータにフォールバックするのに対し、panel get は完全に失敗します。

GRANOLA_API_KEY を使い、sync-api でデータを取り込む場合： パブリック API のメモ、生成された要約、返される場合は所有者のみが閲覧できるプライベートメモ、フォルダーへの所属、話者の帰属情報、全トランスクリプト。メモの詳細取得で HTTP 413 が返された場合、長いトランスクリプトはページネーション対応のトランスクリプトエンドポイントを通じて取得されます。

更新はされませんが、引き続き読み取り可能 — AI チャットスレッド（chat list、chat get）：

チャットだけは更新できません。Granola の内部 API にはチャットエンドポイントがありません（7.465.0 で 7 種類の名前を調査し、2026-08-03 時点ですべて 404）。そのため、ストア内のスレッドは、最後にデスクトップキャッシュを同期したときに取得されたもののままであり、再同期しても追加されません。chat list は人間向けの出力と JSON 出力の両方でその旨を示します。

これらの情報から回答する前に、staleness ブロックを確認してください。 デスクトップキャッシュを読み取れない場合、ストアから読み取ったデータにはこのブロックが含まれます。refreshable は対象のデータを更新できるかどうかを示し、last_catalog_sync_at はレシピのような更新可能なデータの日時を示します。また、last_cache_sync_at はチャットのような更新できないデータの日時を示します。チャットの内容は、話題にしているミーティングより数週間古い場合があります。現在の情報として提示せず、日付を明記してください。

移行済みのインストールで最初のグループに含まれる情報を求められた場合は、そのデータにアクセスできないと伝えてください。トランスクリプトのテキストからパネル、レシピの結果、チャットスレッドを合成しないでください。

Granola のデスクトップアプリにすでにサインインしているのに、なぜ auth login が必要なのか

デスクトップアプリのセッションは共有できないためです。そのトークンは利用資格によってアクセスが制限されたキーの背後にあり、デスクトップアプリとブラウザーが保持するリフレッシュトークンは 1 回しか使えません。つまり、一方をリフレッシュすると、そのクライアントがサインアウトします。そのため CLI は、借用するのではなく、独自のトークンチェーンを保持します。auth login は CLI 専用のデータディレクトリにトークンチェーンを保存し、読み取れるのはあなただけです。auth logout はこれを削除します。ローカルで削除しても、サーバー側では無効化されません。

この CLI を使う場面

Granola.ai のウェブアプリや GUI では答えられない、複数のミーティングにまたがる質問（参加者のタイムライン、MEMO パイプラインの状態、レシピのカバー範囲の不足、カレンダーの重ね合わせ、発言時間の集計）に答える必要がある場合は、granola-pp-cli を使ってください。トランスクリプトをループ処理するエージェント、通話前の準備をする CSM、週次の振り返りを行うコンサルタントに適したツールです。--json のデフォルト出力と --select のドット区切りパスを組み合わせて、エージェントのコンテキストを簡潔に保ちましょう。

この CLI を使用しない場合

ユーザーから明示的に依頼されない限り、リモートの状態を変更しないでください。リモートを変更する操作は、webhooks create / update / delete と meetings delete / restore に限定されています。webhook の削除には --yes が必要です。確認、エクスポート、同期、監査の読み取り、オフラインでの webhook 検証は安全な読み取り操作です。

プラットフォームに関する注意事項

warm <id> <query> は AppleScript を介して Granola のデスクトップ GUI を操作するため、macOS 専用です。デフォルトでは実行予定の内容を表示します。アプリを実際に起動するには --launch を渡してください。macOS 以外のホストでは、「not supported」というメッセージを表示してコマンドは 0 で終了します。その他のコマンドはすべてクロスプラットフォームです。

独自の機能

この API 用の他のツールでは、以下の機能は利用できません。

MEMO パイプライン

• memo run — 1 件のミーティング、またはタイムスタンプ以降のすべての新しいミーティングに対して、preflight → extract パイプラインを実行し、MEMO の 3 ファイルの成果物と ndjson 形式の実行状態台帳を出力します。

  MEMO パイプラインを実行するミーティングごとのシェルループを置き換えます。1 回の呼び出し、1 つの ndjson ストリームで、エージェントが読み取れます。

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

• memo queue — トランスクリプトがキャッシュ内にあるものの、MEMO の 3 ファイルがまだディスク上にないミーティングをすべて一覧表示します。

  ユーザーが Granola を一切開かずに、「まだ MEMO 化されていないものは？」という日々の疑問に答えられます。

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

参加者のインテリジェンス

• attendee timeline — 指定した参加者とのすべてのミーティングを古い順に並べ、各行にタイトル、日付、フォルダー、レシピ適用フラグを表示します。

  1 つのコマンドでミーティング前の準備ができ、数か月にわたる特定の人物との会話の流れを把握できます。

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

• attendee brief — 参加者との直近 N 件のミーティングを取得し、実際にキャッシュされたメモと実際の AI パネルの要約をまとめます。合成は行いません。

  顧客対応責任者が外部との通話前に毎回行っている、ミーティングを 1 件ずつ開いてコピー＆ペーストする作業をなくします。

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

フォルダーとレシピ

• folder stream — Granola フォルダー内のすべてのミーティングについて、メモと名前付きパネルをインライン化した ndjson ストリームを出力します（documentLists + listRules を介して解決）。

  フォルダーを開き、各ミーティングの要約をスプレッドシートにコピー＆ペーストする週次振り返りのワークフローを置き換えます。

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

• recipes coverage — 指定した期間内に、名前付きのパネルテンプレート／レシピが適用されなかったミーティングを表示します。

  「新規見込み客との通話すべてに Discovery レシピを実行したか？」という金曜日の振り返りの疑問に、未適用分を 1 行ずつ表示して答えます。

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

トランスクリプトの分析

• talktime — 1 件のミーティングについて、セグメントのソースごとの発話時間を分単位で表示します。マイク（あなた）とシステム（他の全員）を比較できます。

  信頼度の列でトランスクリプトの正確さを評価できます。マイクとシステムの内訳は、「自分は話しすぎていないか」を振り返るための入力になります。

  granola-pp-cli talktime 196037d9 --json
  

• talktime — 日付以降の N 件のミーティングについて、ソースごとの発話時間の集計を行います。時間の経過に伴う発話量の最多話者が分かります。

  ミーティング単位のツールでは作成できない、時間配分の振り返りに役立つ入力です。

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

キャッシュを基盤とするデータ

以下の 2 つは、どちらも 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 クエリ

ローカルストアは ~/.local/share/granola-pp-cli/data.db にある通常の SQLite データベースです。コマンドでは対応できない質問に対して、データベースに直接クエリを実行する方法もサポートされています。列名を推測するのではなく、まずスキーマを確認してください。よくある間違いは 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 です。スキーマ 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、太字のマーク、段落区切り）を、notes_plain にフォールバックするのではなく、標準の Markdown に変換します。

  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	3 つのストリームを統合したパイプライン。キャッシュを読み込み、MEMO の 3 点セットを書き込みます
ミーティング	meetings list, meetings get, meetings fetch-batch, meetings delete, meetings restore, show	ミーティングの一覧表示、確認、変更（削除／復元は内部 API 経由で変更します）
ストリーム	notes-show, panel get, transcript get, tiptap extract	3 つのストリーム（人間のメモ、AI パネル、トランスクリプト）に個別にアクセスします
エクスポート	export, export-all	3 つのストリームを統合した 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 の組織管理エンティティ
Public-API ミラー	notes list, notes get, folders	型付きの Bearer キーエンドポイント
Public-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 は少なくとも 1 件一致したことを示し、終了コード 2 は確信を持てる一致がなかったことを示します。その場合は --help にフォールバックするか、より絞り込んだクエリを使用してください。

レシピ

毎日の MEMO ループ

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

昨日以降の新しい会議をすべて MEMO の 3 項目形式で処理し、新しい成果物のみを出力します。

通話前の参加者向け概要

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

Trevin との直近 3 件の会議を取得し、各会議についてタイトル、日付、アクションアイテムパネルの内容のみを表示します。

金曜日の振り返り — 不足しているレシピ

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

過去 2 週間に行われた新規見込み客との通話のうち、Discovery パネルが適用されていないものをすべて表示します。スラッグを省略すると、すべてのパネルテンプレートにわたる適用漏れを一覧表示します。

リポジトリ全体の重複整理

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 キーを取得する — 新しいデータを取得する場合のみ必要です

API キーは Granola デスクトップ → 設定 → コネクター → API キー で作成できます。作成には Business または Enterprise の Granola ワークスペースが必要です。個人用および無料のワークスペースではキーを発行できません。スコープは personal-notes と public-notes の 2 種類です。ユーザーが実際に必要とするノートをカバーする、最も範囲の狭いスコープを選んでください。自分の会議を読むユーザーの場合は 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 のまま 4 日間再試行します。一時停止中のエンドポイントには、一時停止中に発生したイベントは配信されず、後から再送されることもありません。

2. 一度データを取り込む

granola-pp-cli sync-api を実行してください。ノート一覧をページごとに取得した後、各ノートの詳細と文字起こしを取得し、会議、参加者、カレンダーイベント、要約、フォルダーの所属情報、文字起こしのセグメントをローカルストアに書き込みます。これらはすべての読み取りコマンドがクエリするテーブルです。繰り返し実行する場合は、--since 7d で対象期間を絞り込んでください。

2 つの同期経路が互いのデータを上書きすることはありません。それぞれが自分の所有する行だけを削除するため、同じストアに対して sync と sync-api をどちらの順序で実行しても安全です。

文字起こしには追加の保護機能があります。Granola は上流で文字起こしの保持期間を適用するため、古い会議を API から取得すると、数件のセグメントだけに削られている場合があります。その一方で、このストアにはキャッシュ経路から取得した完全な録音が残っている可能性があります。一方のソースから取得したより小さいコピーで文字起こしが置き換えられることはありません。保存済みのデータが維持され、その会議はスキップされ、同期の概要に preserved_transcripts として報告されるほか、対象の会議名を示す warning: 行も出力されます。経路が同じ経路で以前に取得した文字起こしを書き換える場合は、サイズが変わっても影響を受けません。

3. キーなしで読み取る

一度同期すれば、すべての読み取りコマンドが認証情報なしでオフライン動作します。granola-pp-cli transcript get <id> --json は、GRANOLA_API_KEY が設定されている場合もされていない場合も、バイト単位で同一の出力を返します。トップレベルの source フィールドは、store（SQLite）、cache（従来のデスクトップキャッシュ）、live（パブリック API または内部 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 を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプで利用可能 — JSON は標準出力に、エラーは標準エラー出力に出力されます

• フィルタリング可能 — --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 を解析してください。人が読める N results (live) の概要は、標準出力が端末の場合にのみ標準エラー出力に表示されます。パイプまたはエージェント経由の利用では、標準出力に純粋な JSON のみが出力されます。

自動更新

すべてのコマンドは、最初の処理としてローカルストアを自動更新します。meetings list、panel get、その他の読み取りコマンドを実行する前に、granola-pp-cli sync を実行する必要はありません。CLI が呼び出しのたびに処理します。

2 つの認証経路はそれぞれ独立して更新されます：

経路	実行される処理	実行条件
デスクトップの暗号化キャッシュ	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 にデータを反映するノートごとの詳細取得が実行されます。ただし、どのコマンドよりも先に実行できるよう、前回の正常な更新以降に変更されたノートを 1 ページ分に制限しており、アカウント全体を取得するわけではありません。新規インストール時には granola-pp-cli sync-api を一度実行して履歴をバックフィルしてください。その後は自動更新によって最新の状態が保たれます。

更新状況の行。 stderr が TTY で、--agent／--json／--compact／--quiet モードでない場合、更新後に auto-refresh: cache=ok (1.2s, 47 rows) api=ok (820ms, 12 rows) のような 1 行のメッセージが stderr に出力されます。エージェントや JSON の利用者には、stdout に余計な出力はありません。

失敗しても致命的ではありません。 更新に失敗すると cache=failed: <short reason> が stderr に出力され、コマンドはストアにすでにあるデータを使って続行します。更新の失敗が続く場合は、原因を調べるために 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 にスキップ対象の全コマンドが表示されます。

エージェントからのフィードバック

この 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 されることはありません。デフォルトの動作はローカルのみです。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で。それが積み重なっていく情報になります。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は stdout に加えて（または stdout の代わりに）指定した sink に送られるため、エージェントはコマンドの結果を手動でパイプしなくても振り分けられます。対応している sink は 3 種類です。

Sink	効果
stdout	デフォルト。stdout のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイル + リネーム）
webhook:<url>	出力本文を URL に POST します（--compact 指定時は application/json または application/x-ndjson）

不明なスキームは、対応する値を列挙した構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードを返し、URL と HTTP ステータスを stderr に記録します。

名前付きプロファイル

プロファイルは、呼び出しをまたいで再利用できるフラグ値の保存セットです。スケジュールされたエージェントが、毎回同じ設定で同じコマンドを呼び出す場合に使用します。これは 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 に一覧表示します。

終了コード

Code	意味
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。