pp-linear

Linear — Printing Press CLI

前提条件：CLI をインストールする

このスキルでは linear-pp-cli バイナリを使用します。このスキルが有効な間は、linear という名前のコマンドを呼び出さないでください。linear-pp-cli が見つからない場合は、まずインストールしてください。

1. Printing Press インストーラーを使ってインストールします。デフォルトでは、macOS/Linux では $HOME/.local/bin に、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin にバイナリがインストールされます。

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

2. 次のコマンドで確認します：linear-pp-cli --version
3. 報告されたインストールディレクトリが、このスキルを呼び出すエージェント／ランタイムの $PATH に含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go から直接インストールしてください（Go 1.26.6 以降が必要です）。

go install github.com/mvanhorn/printing-press-library/library/project-management/linear/cmd/linear-pp-cli@latest

インストール後、--version で「command not found」と表示される場合、ランタイムからバイナリディレクトリを $PATH 経由で参照できていません。確認に成功するまで、スキルのコマンドを実行しないでください。

エージェントの契約

• 人が読みやすい表が明示的に必要な場合を除き、コマンドに --agent を追加してください。このフラグを指定すると、JSON、簡潔な出力、非対話モード、色なし、および確認を安全に行えるスクリプト実行が有効になります。
• 現在の正しい状態が重要なクローズアウト／状態／説明の確認には --data-source live を使用してください。重複の確認には issues search を使用してください。古くなった課題検索データが更新され、更新できない場合はそのことが明示されます。ローカルの重複検索が古いデータを使うことやオフラインであることを意図している場合に限り、--data-source local または similar を使用してください。
• 簡潔な出力に含まれないフィールドも、課題に存在しないとは限りません。ネストしたラベルも含め、必要なフィールドを明示的に指定してください：linear-pp-cli issues ENG-123 --agent --data-source live --select identifier,title,description,state.name,labels.nodes.id,labels.nodes.name,url
• 既知の課題を複数取得する場合は、識別子をカンマ区切りで指定して、1 回の呼び出しにまとめてください：linear-pp-cli issues ENG-123,ENG-124 --agent。結果の配列は呼び出し側が指定した順序を保ち、重複する識別子を除去します。該当する項目が 1 つでも見つからない場合は、部分的な結果ではなく読み取り全体が失敗します。
• ここに示す正式な読み取り形式とコメント形式を優先してください。一般的なエージェント向けの表現も動作を変えずに使用できます：issues get|view|show ENG-123、documents get|view <ref>、comments create は、それぞれ issues ENG-123、documents <ref>、comments add の互換エイリアスです。エイリアスでは、正式なコマンドと同じグローバルフラグ、複数項目の読み取り、本文ファイル、対象、およびメディア用フラグを使用できます。意図的に documents show エイリアスは用意されていません。
• --label は UUID のみを受け付けます。--label-name は書き込み時に、完全一致するラベル名（チーム所有またはワークスペース全体）を解決します。UUID を issues create または issues edit に渡す前に、linear-pp-cli labels list --team ENG --agent --select id,name,global,team.key を実行してください。CLI は所有権を事前確認し、別のチームのラベルであれば変更を拒否します。
• 複数行の Markdown、シェルスニペット、GraphQL、ログ、バッククォート、$() 展開、またはリッチメディアを含む内容を、インラインのシェル引数として渡さないでください。本文をファイルまたは標準入力に書き込み、以下の *-file／*-stdin フラグを使用してください。

この CLI を使用する場面

課題、サイクル、プロジェクト、マイルストーンを横断する結合クエリが必要な場合は、この CLI を使用してください。こうした質問には、Linear の UI では複数のタブを開く必要があり、API では複数回の往復が必要です。MCP 経由で Linear を操作するエージェント（オーケストレーションの組み合わせと名前付きインテントにより、全機能を約 1K トークンでカバーできます）、金曜日の進捗報告を準備するエンジニアリングマネージャー（サイクル比較、予定遅延、バーンダウン、ブロック中の作業キュー）、および pp_created フィクスチャのライフサイクル契約に基づいて実際のワークスペースを変更する必要があるエージェントには、最適な選択肢です。

独自の機能

この API の他のツールでは、これらの機能を利用できません。

蓄積するローカル状態

• today — すべてのチームにわたる、本日割り当てられたすべての課題を、優先度とサイクルの期限順に表示します。

  エージェントや人間が、元となる結合条件を指定せずに、すべてのチームにわたる優先順位付きの単一の作業キューを必要とするときに使います。

  linear-pp-cli today --json --agent
  

• bottleneck — スプリント計画の前に、過負荷のチームメンバーとブロックされている課題を確認します。

  スプリント計画で、誰が過負荷なのか、どこで作業が滞っているのかを一画面で確認したいときに使います。

  linear-pp-cli bottleneck --team ENG --json
  

• stale — N 日間更新されていない課題を、チームとプロジェクトごとにグループ化して見つけます。

  バックログの整理で、API レート制限を使い切らずに忘れられた課題を洗い出したいときに使います。

  linear-pp-cli stale --days 30 --team ENG --json
  

• issues search / similar — ローカルの FTS5 検索を使って、クエリ文字列と類似する課題を見つけます。

  トリアージで、届いたバグ報告が既存の課題と重複していると思われるときに使います。

  linear-pp-cli issues search "login redirect bug" --limit 5 --agent
  linear-pp-cli issues search "pipeline follow-up" --team SYMPH --limit 10 --agent
  linear-pp-cli similar "login redirect bug" --limit 5 --json
  linear-pp-cli similar "pipeline follow-up" --team SYMPH --limit 10 --agent
  

  フォローアップ作業を作成または更新する前に既存のチケットを確認する場合は、issues search を優先してください。これは、エージェントがよく使う、サポート対象の課題検索コマンドです。重複チェックでは、データの鮮度を考慮します。ローカルデータが新しければすぐに検索し、課題データが古いか空の場合は、プロセス間ロックを取得してから検索前に更新します。更新に失敗した場合は、古い結果を黙って返すのではなく、型付きエラーを返します。チーム間で共通のプロジェクト名やラベルが使われており、重複チェックを対象チームのキュー内に限定する必要がある場合は、--team <key-name-or-uuid> を追加してください。複数語の issues search クエリは、引用符で囲むことも、個別の語として渡すこともできます。どちらの場合も、1 つの FTS クエリに結合されます。--agent / --json の場合、issues search は鮮度メタデータを含む出所情報のエンベロープを返しますが、similar は従来の生の結果配列を返します。古いローカル結果やオフラインのローカル結果を意図して使う場合に限り、--data-source local を使用してください。

エンティティ横断の集計

• projects burndown — チームの実測ベロシティに対する残り見積もりの線形回帰から、プロジェクトの完了予定日を予測します。

  ステークホルダーからプロジェクトの完了時期を尋ねられたものの、プロジェクトページに数か月前に入力された固定の目標日しか表示されないときに使います。

  linear-pp-cli projects burndown PROJ_ID --weeks 8 --json
  

• cycles compare — 任意の 2 つのサイクルの指標を並べて比較します。完了率、追加されたスコープ、削除されたスコープ、持ち越し、平均サイクル時間を確認できます。

  サイクルの振り返りや金曜日の進捗報告で、ブラウザーのタブを 2 つ見比べるのではなく、数値で差分を確認したいときに使います。

  linear-pp-cli cycles compare 42 43 --json
  

• slipped — 前のサイクルから今のサイクルに持ち越された項目を、チームと理由のヒューリスティックごとにグループ化して表示します。

  金曜日のステークホルダー向け進捗報告で、保存済みビューだけでなく、前のサイクルから持ち越された項目を構造化されたリストで確認したいときに使います。

  linear-pp-cli slipped --team ENG --json
  

• velocity — 直近 N サイクルのスプリント完了率を追跡し、生産性の傾向を把握します。

  月曜日のスプリント計画で、チームの直近のサイクルだけでなく、実際の完了データに基づいて再調整の判断をしたいときに使います。

  linear-pp-cli velocity --weeks 8 --json
  

• initiatives health — イニシアチブごとにポートフォリオ全体を集計して表示します。子プロジェクトの進捗、マイルストーンの目標日と予測日の比較、遅延フラグを確認できます。

  ポートフォリオレビューで、ステークホルダーが開いたプロジェクトタブ 7 つではなく、イニシアチブ単位の集計を求めているときに使います。

  linear-pp-cli initiatives health --json
  

• milestones at-risk — 予測完了日が目標日を過ぎているポートフォリオのマイルストーンを、遅延の大きさ順に一覧表示します。

  週次のポートフォリオレビューで、どのイニシアチブが健全かではなく、どのマイルストーンが最もリスクにさらされているかを確認したいときに使います。

  linear-pp-cli milestones at-risk --json
  

個人用キュー

• blocking — 自分がブロックしている課題を、下流への影響度（下流の件数 × 下流の優先度）順に表示します。

  毎朝、進行中の課題のうち、下流のチームメイトの作業を滞らせているものを把握したいときに使います。

  linear-pp-cli blocking --json
  

エージェントネイティブの仕組み

• pp-test list — この CLI が現在のセッションまたは指定したセッションで作成した Linear の課題を一覧表示し、その後 pp-cleanup でアーカイブします。 エージェントがセッション中に作成したチケットだけを整理する必要がある場合に使用します。ワークスペースの既存データには触れません。

  linear-pp-cli pp-test list --json
  

• issues create --trust-mode strict — --trust-mode strict が設定されている場合、ローカルの pp_created 台帳にない Linear の課題に対する変更を拒否します。作成時と、今後追加されるあらゆる変更操作で機能します。

  実データのある実際のワークスペースでエージェントを実行する場合に使用します。strict モードにより、誤った変更を確実に防止できます。

  linear-pp-cli issues create --title "Test ticket" --team ENG --trust-mode strict
  

• 親課題とサブ課題のリンク — CLI を離れて生の GraphQL を使わなくても、子課題を作成し、親課題のリンクを設定、変更、解除できます。

  エージェントが課題ツリー、エピック、フォローアップの階層を作成し、親子関係を安全に設定する必要がある場合に使用します。

  linear-pp-cli issues create --title "Child task" --team ENG --parent ENG-123 --description-file /tmp/body.md --agent
  linear-pp-cli issues edit ENG-124 --parent ENG-123 --agent
  linear-pp-cli issues edit ENG-124 --no-parent --agent
  

• チームに対応した課題ラベル — グローバルラベルを含め、対象の Linear チームで有効なラベルを検索し、UUID または完全一致の名前で追加できます。

  ラベルを追加する前に使用してください。--label は UUID のみを受け付けます。入力が人間向けのラベル名の場合は、--label-name を使用してください。Linear は別のチームが所有するラベルを拒否し、CLI は変更前に所有権を確認します。

  linear-pp-cli labels list --team ENG --agent --select id,name,global,team.key
  linear-pp-cli issues create --title "Title" --team ENG --label <global-or-eng-label-id> --agent
  linear-pp-cli issues create --title "Title" --team ENG --label-name "kind:bug" --label-name "source:user-report" --agent
  linear-pp-cli issues edit ENG-123 --label-name "area:review-tooling" --dry-run --agent
  linear-pp-cli issues edit ENG-123 --label-name "area:review-tooling" --agent
  

  --label-name は、課題への書き込みがドライランの場合でも、UUID の解決のために必ず Linear から最新データを読み取ります。書き込みには、正規化されたラベル名との完全一致が必要です。チーム所有のラベルとワークスペース全体のラベル（チームなし）はどちらも解決されますが、別のチームが所有するラベルは解決されません。--label と --label-name は併用できます。変更前に解決された ID は重複が取り除かれます。作成時、CLI は変更結果として返されたラベル ID を検証し、Linear が要求されたラベル一式を追加していない場合は、明示的に失敗します。ローカルへの保存ができない場合でもリモートの課題を復旧できるよう、終了コード 5 のエージェント用エンベロープには created_issue.id、created_issue.identifier、created_issue.url が含まれます。

• プロジェクト名とイニシアチブ名の解決 — 課題の関連付けを書き込む前に、人間向けの名前からポートフォリオオブジェクトを解決します。

  ユーザーから課題識別子とプロジェクト名またはイニシアチブ名が指定された場合に使用します。--project は UUID のみを受け付けます。入力が人間向けのプロジェクト名の場合は、--project-name を使用してください。

  linear-pp-cli projects list --agent --select id,name,team.key,state,url
  linear-pp-cli projects search "Autonomous Backlog Manager & Dispatch Governance" --team SYMPH --agent --select id,name,team.key,initiative.name,url
  linear-pp-cli initiatives list --agent --select id,name,status,url
  linear-pp-cli initiatives search "Dispatch Governance" --agent --select id,name,status,url
  linear-pp-cli issues edit SYMPH-795 --project-name "Autonomous Backlog Manager & Dispatch Governance" --dry-run --agent
  linear-pp-cli issues edit SYMPH-795 --project-name "Autonomous Backlog Manager & Dispatch Governance" --agent
  

  --project-name は、課題への書き込みがドライランの場合でも、UUID の解決のために必ず Linear から最新データを読み取ります。名前が部分的な場合は、まず projects search を使用してください。書き込みには、正規化されたプロジェクト名との完全一致が必要です。

• メディアを含む、シェルで安全な Linear への書き込み — Markdown 本文をシェルコマンドラインに記述せずに、課題の説明、コメント、Linear ドキュメントを作成および更新できます。

  本文に改行、引用符、バッククォート、$() の展開、シェルコマンド、画像、ログ、またはエージェントが生成した Markdown が含まれる場合は、いつでも使用してください。

  linear-pp-cli issues create --title "Title" --team ENG --description-file /tmp/body.md --media /tmp/screenshot.png --agent
  linear-pp-cli issues edit ENG-123 --description-file /tmp/body.md --agent
  linear-pp-cli issues edit ENG-123 --media /tmp/screenshot.png --agent
  linear-pp-cli comments add --issue ENG-123 --body-file /tmp/comment.md --media /tmp/screenshot.png --agent
  linear-pp-cli comments edit <comment-id> --body-file /tmp/comment.md --agent
  linear-pp-cli documents create --title "Runbook" --issue ENG-123 --content-file /tmp/runbook.md --agent
  linear-pp-cli documents create --title "Team runbook" --team ENG --content-file /tmp/runbook.md --agent
  linear-pp-cli documents edit <document-id-or-slug> --content-file /tmp/updated.md --agent
  

  documents create には親がちょうど 1 つ必要です（--issue、--project、--team、--initiative、--cycle、--release、または --folder）。--team には ENG などのキーまたは UUID を指定できます。issues edit --media、comments edit --media、documents edit --media で本文またはコンテンツのフラグを指定しない場合、既存の Markdown を Linear から最新の状態で取得し、アップロードしたメディアのリンクを追記します。画像は Markdown の画像埋め込みになり、画像以外は Markdown のリンクになります。アップロードしたアセットを Linear ワークスペース外からも利用できるようにする必要がある場合に限り、--media-public を追加してください。

• 最新の課題読み取りとコメント — 古いローカル状態に頼らず、課題の本文全体とディスカッションを読み取ります。comments list では、課題を位置引数（推奨）または --issue で指定できます。

  linear-pp-cli issues ENG-123 --agent --data-source live --select identifier,title,description,state.id,state.name,labels.nodes.id,labels.nodes.name,url
  linear-pp-cli issues ENG-123,ENG-124 --agent --data-source live --select identifier,title,description,state.name,url
  linear-pp-cli comments list ENG-123 --agent
  linear-pp-cli comments list --issue ENG-123 --agent --limit 100
  

• 状態の遷移 — 生の SQL、GraphQL、または api を調べ回ることなく、課題をワークフローの状態間で移動できます。正確な手順は次のとおりです。

  1. 課題のチームの状態を一覧表示します：workflow-states list --team <key>（エイリアス：states list）。
  2. name または type で対象を選び、その id UUID をコピーします。
  3. その UUID を issues edit --state に渡します。

  linear-pp-cli workflow-states list --team ENG --agent --select id,name,type
  linear-pp-cli issues edit ENG-123 --state <state-uuid> --agent
  

  または、検索を省略し、課題自身のチームに照らして解決するワンコマンドの状態遷移を利用できます。

  linear-pp-cli issues edit ENG-123 --state-name "In Progress" --agent
  linear-pp-cli issues edit ENG-123 --state-type started --agent   # usage error if the team has several 'started' states
  

  issues create は同じ 3 点セットを受け取り、--team に対して解決されるため、イシューを正しい状態で直接開くことができます。--state には UUID が必要です（UUID 以外の値を指定すると、--state-name を指し示す使用エラーになります）:

  linear-pp-cli issues create --title "..." --team ENG --state-name "In Progress" --agent
  

  ワークフローステートには linear-pp-cli api や linear-pp-cli sql を使用しないでください — api は生成された REST 形式のインターフェース（現在は integrations）のみを公開しており、Linear GraphQL オブジェクトは公開していません。

• Linear ドキュメントの読み取り — documents <ref> は Linear が提示するすべての識別子形式を受け付けます: ドキュメント UUID、ベアの slugId（f7f48ab36080）、完全な URL スラッグ（my-runbook-f7f48ab36080）、またはドキュメント URL 全体です。手持ちのものをそのままコピーしてください。スラッグのトリミングや解析のシムは不要です。

  linear-pp-cli documents my-runbook-f7f48ab36080 --agent --select title,updatedAt,content
  linear-pp-cli documents "https://linear.app/<org>/document/my-runbook-f7f48ab36080" --agent
  

コマンドリファレンス

attachments — 添付ファイルを管理します

• linear-pp-cli attachments <id> — 単一の添付ファイルを取得します

audit-entry-types — audit-entry-types を管理します

• linear-pp-cli audit-entry-types — 単一の auditentrytype を取得します

auth-resolver-responses — auth-resolver-responses を管理します

• linear-pp-cli auth-resolver-responses — 単一の authresolverresponse を取得します

authentication-session-responses — authentication-session-responses を管理します

• linear-pp-cli authentication-session-responses — 単一の authenticationsessionresponse を取得します

email-intake-addresses — email-intake-addresses を管理します

• linear-pp-cli email-intake-addresses <id> — 単一の emailintakeaddress を取得します

favorites — お気に入りを管理します

• linear-pp-cli favorites <id> — 単一のお気に入りを取得します

initiative-relations — initiative-relations を管理します

• linear-pp-cli initiative-relations <id> — 単一の initiativerelation を取得します

initiative-to-projects — initiative-to-projects を管理します

• linear-pp-cli initiative-to-projects <id> — 単一の initiativetoproject を取得します

initiatives — イニシアチブを管理します

• linear-pp-cli initiatives <id> — 単一のイニシアチブを取得します
• linear-pp-cli initiatives list — Linear のイニシアチブを一覧表示します
• linear-pp-cli initiatives search <query> — 名前で Linear のイニシアチブを検索します
• linear-pp-cli initiatives resolve <name> — Linear のイニシアチブ名 1 件をその UUID に解決します

integrations — インテグレーションを管理します

• linear-pp-cli integrations create — インテグレーションを作成します
• linear-pp-cli integrations delete — インテグレーションを削除します

issue-priority-values — issue-priority-values を管理します

• linear-pp-cli issue-priority-values — 単一の issuepriorityvalue を取得します

labels — チームの所有権を含む Linear のイシューラベルを一覧表示します

• linear-pp-cli labels list --team ENG — グローバルラベルと対象チームが所有するラベルを一覧表示します

organizations — 組織を管理します

• linear-pp-cli organizations — 単一の組織を取得します

project-labels — project-labels を管理します

• linear-pp-cli project-labels <id> — 単一の projectlabel を取得します

project-milestones — project-milestones を管理します

• linear-pp-cli project-milestones <id> — 単一の projectmilestone を取得します

project-relations — project-relations を管理します

• linear-pp-cli project-relations <id> — 単一の projectrelation を取得します

project-statuses — project-statuses を管理します

• linear-pp-cli project-statuses <id> — 単一の projectstatus を取得します

project-updates — Linear のプロジェクト更新（プロジェクトに対するステータス投稿）を作成および一覧表示します

• linear-pp-cli project-updates list --project <uuid> --agent — プロジェクトのプロジェクト更新を一覧表示します
• linear-pp-cli project-updates list --project-name "My Project" --limit 10 --agent — プロジェクト名で更新を一覧表示します
• linear-pp-cli project-updates create --project <uuid> --body-file /tmp/update.md --health onTrack --agent — markdown 本文付きでプロジェクト更新を投稿します
• linear-pp-cli project-updates create --project-name "My Project" --body "Sprint on track." --health onTrack --agent — プロジェクト名で更新を投稿します
• linear-pp-cli project-updates create --project <uuid> --body-stdin --health atRisk --agent < /tmp/update.md — stdin から更新を投稿します

projects — プロジェクトを管理します

• linear-pp-cli projects <id> — 単一のプロジェクトを取得します
• linear-pp-cli projects list — Linear プロジェクトを一覧表示します
• linear-pp-cli projects search <query> — 名前で Linear プロジェクトを検索します
• linear-pp-cli projects resolve <name> — 1 つの Linear プロジェクト名をその UUID に解決します

release-notes — release-notes を管理します

• linear-pp-cli release-notes <id> — 単一の releasenote を取得します

release-pipelines — release-pipelines を管理します

• linear-pp-cli release-pipelines — 単一の releasepipeline を取得します

release-stages — release-stages を管理します

• linear-pp-cli release-stages <id> — 単一の releasestage を取得します

releases — releases を管理します

• linear-pp-cli releases <id> — 単一の release を取得します

roadmap-to-projects — roadmap-to-projects を管理します

• linear-pp-cli roadmap-to-projects <id> — 単一の roadmaptoproject を取得します

roadmaps — roadmaps を管理します

• linear-pp-cli roadmaps <id> — 単一の roadmap を取得します

teams — teams を管理します

• linear-pp-cli teams — 単一の team を取得します

templates — templates を管理します

• linear-pp-cli templates — 単一の template を取得します

user-settingses — user-settingses を管理します

• linear-pp-cli user-settingses — 単一の usersettings を取得します

users — users を管理します

• linear-pp-cli users — 単一の user を取得します

workflow-states — Linear のワークフローステートを一覧表示します（エイリアス: states）

• linear-pp-cli workflow-states list --team ENG --agent --select id,name,type — issues edit --state が必要とする UUID を含めて、チームのステートを一覧表示します

適切なコマンドの見つけ方

やりたいことは分かっているが、どのコマンドがそれを行うか分からないときは、CLI に直接尋ねてください:

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

which は自然言語による機能クエリを、この CLI の厳選された機能インデックスから最も一致するコマンドに解決します。終了コード 0 は少なくとも 1 件の一致を意味し、終了コード 2 は確信のある一致がないことを意味します。その場合は --help に頼るか、より絞り込んだクエリを使用してください。

重複チェックの場合、linear-pp-cli which "search issues by text" --agent は issues search を指すはずです。issues search --help というフォールバックをでっち上げたり生の SQL を使ったりする代わりに、こちらを使用してください。ローカルの issue キャッシュが古い場合、issues search はそれを更新するか、型付きの鮮度エラーで失敗します。キャッシュが古かったというだけで、エージェントが生の GraphQL に飛びつくべきではありません。 親/サブ issue のリンクについては、linear-pp-cli which "set issue parent" --agent が issues edit --parent を指すはずです。

レシピ

金曜日のステークホルダー向けアップデート

linear-pp-cli cycles compare current previous --json --select completionPct,scopeAdded,scopeCut,carryover,meanCycleTimeHours

現在のサイクルと前のサイクルの 2 行の差分を、ステークホルダー向けドキュメントに入る 5 つのフィールドに絞り込んだもの — お好みの LLM にパイプして文章を書かせてください。

エージェント向けの日次 what-now

linear-pp-cli today --json --agent --select id,identifier,title,state.name,cycle.endsAt,priority

エージェントが何に取り組むかを決めるために必要なフィールドだけを含む、ランク付けされた作業キュー。--agent はエージェントモードのエンベロープを有効にし、--select はペイロードをキロバイト単位から 1 行あたり約 200 バイトに絞り込みます。

スプリントプランニングの再調整

linear-pp-cli bottleneck --team ENG --json | jq '.[] | select(.loadIndex > 1.2)'

担当者ごとの負荷を取得し、過負荷の部分を jq にパイプします — ボトルネックのコマンドが結合を明らかにし、jq がフィルタリングを行うので、コマンドは組み合わせ可能なままです。

バックログ整理の一掃

linear-pp-cli stale --days 60 --team ENG --json --select identifier,title,assignee.name,updatedAt

厳選された --select プロジェクションによる古い issue のスキャン。多数の呼び出しにわたってコンテキストに保持できるほど小さいものです。

エージェントのフィクスチャのクリーンアップ

linear-pp-cli pp-test list --session current --json && linear-pp-cli pp-cleanup --session current

一覧表示してから、この CLI が現在のセッションで作成した issue のみをアーカイブします — 既存のワークスペースデータには決して触れません。

認証のセットアップ

Linear の個人用 API キーは Authorization ヘッダーにそのまま入れます — Bearer プレフィックスは付けません。linear-pp-cli auth set-token lin_api_yourkeyhere を実行してキーを保存するか（Linear の個人用 API キーには Bearer プレフィックスは不要です）、LINEAR_API_KEY=lin_api_... をエクスポートしてください。個人用 API キーはワークスペース単位です。doctor コマンドは認証、API 接続性、ストアの健全性を一度に検証します。

linear-pp-cli doctor を実行してセットアップを確認してください。

鮮度とデータソース（エージェントループで操作する前にこれを読んでください）

コマンドは、データソースのセマンティクスが異なる3つのカテゴリに分かれています。読み取り元を制御するには --data-source auto|live|local を使用し、「ローカルデータが古くなっています」というヒントのしきい値を設定するには --max-age <duration> を使用します。

カテゴリ1：ライブ優先、ローカルにフォールバック（仕様から生成されたコマンドと、v4でリファクタリングされた issues list/get）

• attachments <id>、projects get <id>、teams <id>、initiatives get <id>、issues <id>、issues list など
• デフォルト（--data-source auto）：Linear の API にアクセスし、レスポンスをローカルストアにも書き込みます。ネットワークエラー（DNS／タイムアウト／接続拒否）が発生した場合に限り、ストアにフォールバックします。4xx および 5xx エラーはそのまま返され、古いデータが暗黙に使用されることはありません。
• --data-source live：常に API にアクセスし、フォールバックは行いません。エージェントに最新のデータを必ず使わせたい場合や、古いデータを返すより明示的に失敗させたい場合に使用します。
• --data-source local：API にはアクセスしません。Linear の複雑性予算（個人用キーでは約1500ポイント／時間）を節約するため、エージェントの短いループ内で使用します。
• teams や projects get など、Linear GraphQL を利用するようになった読み取りコマンドは、内部で POST /graphql を使用します。シェルから GET /graphql を呼び出す形で再現しないでください。Linear はその形式を CSRF／プリフライトエラーで拒否します。

カテゴリ2：スナップショットを使った計算（必要上、ローカルのみ）

• today、bottleneck、blocking、similar、velocity、slipped、cycles compare、projects burndown、initiatives health、milestones at-risk
• 同期済みデータ全体に対する結合／集計／FTS5 マッチングを行います。この形式の結果を返す単一の Linear API 呼び出しはありません。--data-source フラグは無視され、常にローカルストアから読み取ります。
• これらを使用する前に sync を実行してください。 初回起動時のヒント：結果が空の場合、(no <resource> in local store — run 'linear-pp-cli sync' to populate) が stderr に出力されます。
• 古いデータのヒント：ローカルストアが --max-age（デフォルトは30分）以内に同期されていない場合、読み取り時に (<resource> data is Xm old, exceeds --max-age=30m — run 'linear-pp-cli sync' to refresh) が stderr に出力されます。--json の出力はそのままです（ヒントは stderr にのみ出力されます）。

鮮度を調整するローカル検索

• issues search
• ローカルの FTS 課題インデックスを使用しますが、重複チェックのために鮮度を調整します。課題データが十分に新しければ、すぐに検索します。課題データが古いか空の場合は、プロセス間ロックを取得し、チーム、ワークフローステート、ラベル、課題を更新してから検索します。
• 更新に失敗した場合、古い重複検索結果を返す代わりに、--agent のもとで型付き JSON エラーを出力します。エージェント／JSON 出力は、鮮度メタデータを含む出所情報のエンベロープです。refreshed は呼び出し中にローカルの課題データが変更されたことを示し、refreshed_by は変更を行ったのがこのプロセス、別のプロセス、外部同期のいずれかを示します。明示的にオフライン／古いデータのモードを使用する場合に限り、--data-source local を使用してください。JSON メタデータには、この古いローカルデータを使うポリシーが記録されます。鮮度チェックを意図的に無効化する場合に限り、--max-age 0 を使用してください。メタデータには freshness_gate_disabled が記録されます。空のローカルストアには unsynced が記録されます。

カテゴリ3：変更操作

• issues create、issues edit、comments add、comments edit、documents create、documents edit、pp-cleanup
• 常に API にアクセスします。成功すると、HTTP レスポンスキャッシュが無効化され、新規または変更されたエンティティがローカルストアにも書き戻されます。そのため、次に issues list --data-source local を実行すると、再度同期しなくても変更が反映されます。

ライブのみのコラボレーション関連の読み取り

• comments list、documents <id-or-slug>、documents list
• コメントや作業セッションのドキュメントはコラボレーションに関わる情報であり、ローカルの古い状態は役に立つどころか誤解を招きやすいため、現在の Linear API から読み取ります。

ラベルの検出

• labels list --team ENG
• デフォルト（--data-source auto）ではライブデータを読み込み、グローバルラベルと、指定したチームが所有するラベルを返します。--data-source local では、linear-pp-cli sync の実行後に同期された issue_labels テーブルを読み込みます。
• 返された ID は issues create --label または issues edit --label で使用できます。または、create/edit で --label-name を指定すれば UUID の検索を省略できます。他チームのラベル ID や、他チームが所有するラベル名は、issue の変更リクエストを送信する前に拒否されます。

予算を意識したエージェントのループ：

# 1. Hydrate once (one batched query for everything)
linear-pp-cli sync

# 2. Read freely — store-backed, zero budget
linear-pp-cli today
linear-pp-cli bottleneck --team ENG --data-source local

# 3. Mutate — write-back keeps the store fresh
linear-pp-cli issues create --title "..." --team ENG --pp-session "$SESSION"

# 4. Verify the mutation from local (no extra API call)
linear-pp-cli issues list --data-source local --pp-session "$SESSION"

# 5. Re-sync every ~30 minutes if the session is long
linear-pp-cli sync

クリーンアップの仕様：

すべての issues create は、新しいチケットをセッション情報付きでローカルの pp_created テーブルに記録します（デフォルト：タイムスタンプ。--pp-session <tag> または PP_SESSION 環境変数で上書きできます）。pp-cleanup --session <tag> は、実際の Linear のアーカイブミューテーションを使って、そのチケットのみをアーカイブします。--trust-mode strict を指定すると、pp_created にない issue の変更を拒否します。セッションタグと併用すれば、エージェントによるワークスペースの汚染を確実に防ぐための下限を設けられます。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ可能 — stdout に JSON を出力します。エラーも JSON です。--agent／--json モードでは、型付きエラー（usage、not-found、auth、API、rate-limit、config）はすべて stdout に1行のエンベロープとして出力されるため、stdout をそのまま JSON パーサーに渡しても安全です。

  {"error":"document \"missing-doc\" not found","code":3,"type":"not_found"}
  

  プロセスは引き続き Exit Codes テーブルに記載された型付きコードで終了します。type はその機械可読名（usage、not_found、auth、api、partial_failure、rate_limit、config）です。読み取り処理で 2>&1 | python json のような防御的なラッパーを使う必要はありません。

• フィルタ可能 — --select でフィールドを絞り込めます。ドット区切りのパスでネストした構造をたどり、配列では各要素をたどります。冗長な API から得られるコンテキストを小さく保つうえで重要です。

  linear-pp-cli attachments mock-value --agent --select id,name,status
  

• プレビュー可能 — --dry-run で、リクエストを送信せずに内容を表示します

• オフラインでも使いやすい — sync/search コマンドでは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトは表示されず、入力はすべてフラグで指定します

• 再試行の明示的な指定 — すでに存在するものの作成を成功として扱う場合にのみ --idempotent を使い、削除対象が見つからない場合に成功として扱う場合にのみ --ignore-missing を使います

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力をプロベナンスエンベロープでラップします。

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

データには .results を解析し、ライブデータかローカルデータかの判別には .meta.source を確認してください。人間向けの N results (live) という概要は、stdout がターミナルで、かつ機械可読形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が指定されていない場合に限り、stderr に出力されます。パイプやエージェントでの利用、および形式を明示的に指定した実行では、stdout に純粋な JSON が出力されます。

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

あなた（またはエージェント）がこの CLI の気になる点に気づいたら、記録してください。

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

エントリーは ~/.linear-pp-cli/feedback.jsonl にローカル保存されます。LINEAR_FEEDBACK_ENDPOINT が設定され、かつ --send が渡されるか LINEAR_FEEDBACK_AUTO_SEND=true が設定されない限り、POST されることはありません。デフォルトの動作はローカル保存のみです。

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

出力の配信

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

シンク	動作
stdout	デフォルト。stdout のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（tmp + rename）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

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

名前付きプロファイル

プロファイルは、保存されたフラグ値のセットで、複数回の実行で再利用できます。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用します。これは HeyGen の「Beacon」パターンです。

linear-pp-cli profile save briefing --json
linear-pp-cli --profile briefing attachments mock-value
linear-pp-cli profile list --json
linear-pp-cli profile show briefing
linear-pp-cli profile delete briefing --yes

明示的なフラグは常にプロファイル値より優先され、プロファイル値はデフォルト値より優先されます。agent-context は、エージェントが実行時にプロファイルを見つけられるよう、利用可能なすべてのプロファイルを available_profiles の下に一覧表示します。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が正しくありません）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待ってから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → linear-pp-cli --help の出力を表示
2. install で始まる場合 → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照
3. それ以外 → 直接使用（--agent を付けて CLI コマンドとして実行）

MCP サーバーのインストール

この CLI の公開ライブラリーエントリーまたはビルド済みリリースから MCP バイナリをインストールし、登録します。

claude mcp add linear-pp-mcp -- linear-pp-mcp

確認：claude mcp list

直接使用

1. インストールされているか確認します：which linear-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある前提条件を参照）。
2. ユーザーのクエリに最適なコマンドを、上記の独自の機能とコマンドリファレンスから選びます。
3. --agent フラグを付けて実行します。

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

4. あいまいな場合は、サブコマンドのヘルプを確認します：linear-pp-cli <command> --help。