SuperFlow CLI

保存したアイテムを検索・出力し、Markdown でパイプして AI エージェント（Claude Code / Codex）へ素材として渡す（Pro 想定）。依存ゼロ（Node 18+ 組み込みのみ）。

コマンドは superflow と短縮エイリアス sf のどちらでも実行できる。

インストール

npm install -g superflow-cli

ローカル開発時は cd cli && npm install -g .（もしくは npm link）。

AI エージェント（Claude Code / Codex 等）にセットアップを任せるなら、次のURLを渡せばインストールから認証まで案内される: https://super-flow.ai/cli-install.md

使い方

superflow login                          # トークン発行＋認証確認（solo モードはブラウザ不要）
superflow list [--unread|--read] [--limit N] [--brief]
superflow recent [--limit N] [--brief]   # 直近 N 件（既定10）
superflow search "<query>" [--starred] [--tag T] [--since 7d|24h|2w] [--only ...]
superflow read <id> [<id> ...] [--only summary|highlight|memo]   # 複数IDをまとめて読める
superflow save <url> [--memo "…"] [--wait]  # URL を保存（--wait は要約の完成まで待つ）
superflow highlights [--since 30d] [--limit N] [--format=json]   # ハイライト集約（既定は全期間）
superflow export                         # 全件を Markdown でエクスポート
superflow open <id>                      # Web 版で開く
superflow token list                     # CLI トークン一覧
superflow token revoke <id> [--yes]      # トークンを失効
superflow doctor                         # 接続先・認証の疎通確認
superflow version                        # バージョン表示（--version / -v も可）

--format=json で JSON 出力（パイプ時は自動でJSON）。--format=md でパイプ時もMarkdownで出力（明示指定が最優先）。--format json のように空白区切りでも指定できる。<id> は先頭数文字の短縮IDでも可（一意に定まる場合）。

直近 N 件を1コマンドで把握する

list / recent は、--format=md を明示したとき（および JSON 出力のとき）に中身込みで出す。1件あたり要約・主要なポイント・引用（ハイライト）・メモまで含み、アイテム同士は --- で区切る。「直近30本を踏まえて考える」ような用途で、1件ずつ read して回る必要はない。

superflow recent --limit 30 --format=md   # 直近30本を要約・ハイライト・メモ込みで一括把握
superflow recent --limit 30 --brief       # タイトルだけの1行一覧が欲しいとき

ターミナルで --format を付けずに実行したときは、従来どおりタイトルの1行一覧のまま（画面を埋めない）。--brief は --format=md を指定していても1行一覧に戻すフラグ。

read は複数のIDを並べて渡せる（superflow read <id1> <id2> <id3>、最大50件）。Markdown は --- 区切りで連結し、JSON は配列で返す。途中のIDで失敗した場合はその時点で止まり、どのIDで失敗したかをメッセージに含める。

highlights は既定で全期間（読了済み全件）の集約なので、古い素材が混ざる。直近だけを対象にするなら --since 30d、件数を抑えるなら --limit N を付ける。--since を付けずに実行したときは、その旨を stderr に1行警告する（stdout の JSON / Markdown は汚さない）。

superflow highlights --since 30d --limit 100

--since は 7d（日）/ 24h（時間）/ 2w（週）の形式（search / highlights）。--limit は 1 以上の整数。形式が違うときは黙って無視せず、使い方エラー（終了コード 2）で止まる。

read / open で参照できるのは読了済みのアイテムのみ（list / recent には未読も表示され、未読には [未読] が付く）。未読のIDを read すると「読了済みのアイテムが見つかりません」（終了コード 4）になる。

保存はできる（削除・変更はできない）

CLI トークンでできるのは検索・閲覧と保存（2026-08-19 の方針変更。それまでは読み取り専用だった）。権限を選ぶUIはなく、これが既定。

superflow save https://example.com/article                  # URL を保存
superflow save https://example.com/article --memo "引用したい箇所"
superflow save https://example.com/article --wait           # 要約の完成まで待つ（最大60秒）

保存はプランの保存枠を消費する（Web / Chrome拡張 / iOS と同じ枠）。サーバー側のレート制限（20回/分）も同じように効く。上限に達したときは終了コード 5 で止まる。AI エージェントに使わせる場合は、本人が求めたときだけ保存させること（一括保存の乱発をしない）。

一方で、削除・更新（読了/★の切り替え、メモ、ハイライト、要約の再生成、読み上げ音声の生成、課金操作など）はできない。これらの API は CLI トークンからのアクセスをサーバー側で 403 拒否する。

CLIトークンでできる変更は保存（追加）だけです。削除・変更は SuperFlow のWebアプリから行ってください。
{"error":"read_only_token","message":"CLIトークンでできる変更は保存（追加）だけです。…"}

スラッグ read_only_token は互換のため据え置き（出荷済みの 0.5.x がこの値で表示を分岐している）。意味は「保存以外の変更は不可」。

AI エージェントに CLI を渡しても、既にあるアイテムが消えたり書き換わったりはしない（増えるだけ）。ブラウザ拡張のトークンはこの制限を受けない。

例

superflow save https://example.com/article --memo "後で引用する"
superflow search "AI" | claude code "これを元に note の下書きを作って"
superflow recent --limit 30 --format=md       # 直近30本を要約・ハイライト・メモ込みで一括把握
superflow read <id1> <id2> --format=md       # 複数アイテムをまとめて読む
superflow highlights --since 30d             # 直近30日のハイライトだけ集約
superflow read <id> --only highlight,memo    # 自分が触れた痕跡だけ
superflow read <id> --format=md | claude code "この素材から下書きを作って"
superflow read <id> --format=json | jq .

終了コードとエラー出力（AIエージェント向け）

エラーは stderr に日本語1行で出す。加えてパイプ時（非TTY）または --format=json 時は、機械的に解釈できる1行JSONも stderr に出す。

読了済みのアイテムが見つかりません。
{"error":"not_found","message":"読了済みのアイテムが見つかりません。"}

error は機械可読なスラッグ（usage / auth / not_found / rate_limited / daily_limit / plan_required / read_only_token / ambiguous / network / timeout / bad_response / api_error など）。レート制限系では retryAfter（秒）が付く。

| 終了コード | 意味 | | --- | --- | | 0 | 成功 | | 1 | その他のAPIエラー | | 2 | 使い方エラー（オプションの指定ミス・短縮IDが曖昧・保存以外の変更操作の拒否） | | 3 | 認証エラー（未ログイン・トークン不正） | | 4 | 見つからない（未読・存在しないID） | | 5 | レート制限・利用上限・プラン不足 | | 6 | ネットワークエラー・タイムアウト（リクエストは30秒で打ち切る） |

provenance（出所を偽らない）

SuperFlow は「読む人のための第二の脳」。第二の脳は出所を偽らない。read / search は 1 件の中身を 3 つの出所に区別 して出力する。

• 要約（AI要約・原文未接触） … AI が生成した要約本文と主要ポイント。あなたが原文で触れた箇所ではない。
• 引用（原文で選択したハイライト） … あなたが原文で選択したハイライト。
• メモ（あなたの言葉） … あなた自身が書いたメモ。

--only で出所を絞れる（カンマ区切り可）。値は summary / highlight / memo。

superflow read <id> --only summary            # AI要約だけ
superflow read <id> --only highlight,memo     # 自分が触れた痕跡だけ
superflow search "AI" --only memo             # メモを対象に検索

設定

• 設定ファイル: ~/.superflow/config.json（{ endpoint, token }、パーミッション 0600 / ディレクトリ 0700）
• 既定接続先: https://super-flow.ai

環境変数

• SUPERFLOW_TOKEN … トークン（config.json の token より優先）
• SUPERFLOW_ENDPOINT … 接続先 URL の上書き
• SUPERFLOW_NO_BROWSER=1 … login でブラウザを自動で開かない（認証URLは表示され、自動受け渡しは有効）
• SF_JSON=1 … 常に JSON 出力

認証

• solo モード（DB あり・認証 off）: superflow login が /api/cli/token を直接叩いてトークンを発行（ブラウザ認証不要）。
• 多人数モード（Supabase認証）: ブラウザ認証を自動で受け渡す（コピペ不要）。
  1. superflow login を実行するとブラウザが開く（開かない場合は表示された認証URLを開く）。
  2. ブラウザで SuperFlow にログインする。
  3. 「接続を許可」を押すと、トークンが手元の CLI へ自動で戻り、そのまま自動で完了する。
  • CLI はローカルの 127.0.0.1:<ランダムポート> で待ち受け、state を照合して受け取る。ブラウザには「✓ 認証完了」と表示されるので、タブを閉じてターミナルに戻ればよい。
  • 手動で貼り付けたい場合は、CLI のプロンプトにトークンを貼り付けて Enter でも完了できる。
  • SUPERFLOW_NO_BROWSER=1 を付けると自動でブラウザを開かない（SSH・CI 向け）。表示された認証URLを別端末のブラウザで開けば、そのまま自動受け渡しが働く。
• ログインは /api/cli/token での認証確認に通ったトークンだけを保存する（確認に失敗した場合は既存の config.json を書き換えない）。保存は一時ファイル → rename の原子的書き込み。接続や認証が怪しいときは superflow doctor で診断できる。