pp-trigger-dev

Trigger.dev — Printing Press CLI

前提条件：CLI のインストール

このスキルは trigger-dev-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使用してインストールします。バイナリの既定のインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

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

2. 確認します：trigger-dev-pp-cli --version
3. このスキルを実行するエージェント／ランタイムの $PATH に、報告されたインストール先ディレクトリが含まれていることを確認します。

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

go install github.com/mvanhorn/printing-press-library/library/developer-tools/trigger-dev/cmd/trigger-dev-pp-cli@latest

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

この CLI を使う場面

エージェントのタスクで Trigger.dev をプログラムから操作する必要がある場合に、この CLI を使用してください。たとえば、失敗した実行のトリアージ、スケジュールの健全性監査、環境間の環境変数の差分確認、実行全体の LLM コスト計算、新たな失敗の監視などです。開発時のデプロイ／初期化／開発に重点を置く公式の trigger.dev CLI を補完し、管理 API の機能を、スクリプト化できるエージェントネイティブなコマンドとして公開します。オフラインの FTS と型付き終了コードにも対応しています。

独自の機能

この API の他のツールでは利用できない機能です。

リアルタイムのターミナルアラート

• runs watch — 新たな失敗が発生していないか実行を監視し、発生した瞬間にターミナルを中断します。デスクトップ通知、サウンド、シェルループと組み合わせられるゼロ以外の終了コードを出力します。

  エージェントやオンコールエンジニアが、ダッシュボードをポーリングしたりメールを待ったりせず、失敗の発生と同時に対応する必要がある場合に使用してください。

  trigger-dev-pp-cli runs watch --task daily-digest --notify --sound
  

積み重なるローカル状態

• schedules stale — 発火しなくなったスケジュール、または最近の実行成功率が低いスケジュールを一覧表示します。他のツールにはない、ゾンビ化した cron の監査機能です。

  環境変数のローテーション、Postgres URL の変更、または誰にも気づかれないまま cron が停止した可能性のある設定変更の後に使用してください。

  trigger-dev-pp-cli schedules stale --days 7 --min-success-rate 0.5 --agent
  

• runs span-cost — 最近の実行を調べ、最も高額な LLM スパンをモデルとタスクごとにまとめ、トークン合計とドル建てコストを表示します。財務責任者が実際に求めているレポートです。

  請求サイクルが締まる前に、AI プロダクトエンジニアやエージェントが、どのモデルとタスクの組み合わせで LLM 予算を消費しているかを特定する場合に使用してください。

  trigger-dev-pp-cli runs span-cost --since 7d --by model,task --top 20 --agent --select spans.model,spans.task_identifier,spans.total_cost_cents
  

• failures top — 指定した期間内で繰り返し発生する（タスク、エラーシグネチャ）の組み合わせを上位から表示します。機械的なグループ化を行い、LLM も NLP も使用しません。

  インシデント対応中に、エージェントがスタックトレースを 200 件手作業で読む代わりに、最も多いエラーシグネチャを特定する必要がある場合に使用してください。

  trigger-dev-pp-cli failures top --since 7d --top 20 --agent --select patterns.task_identifier,patterns.error_signature,patterns.count,patterns.last_occurred_at
  

• runs find — 同期済みの実行テーブルを対象に FTS5 で検索します。エラーメッセージ、タグ、メタデータ、タスク識別子を、最新のものから順位付けします。

  エージェントがエラーメッセージの一部を手がかりに、TRQL を入力せずに該当する実行を探す場合に使用してください。

  trigger-dev-pp-cli runs find "payload too large" --status FAILED --since 30d --agent
  

運用管理の衛生

• envvars diff — 2 つの環境間の環境変数を左右に並べて比較します。不足しているキー、余分なキー、異なる値（マスク済み）を確認できます。

  「ステージングでは動くのに本番では失敗する」問題をエージェントがデバッグする場合に使用してください。原因はほぼ必ず環境変数であり、diff を使えば答えを 1 つのコマンドで見つけられます。

  trigger-dev-pp-cli envvars diff --from prod --to staging --project proj_abc --agent
  

エージェントの使いやすさ

• runs get — runs get は型付き終了コードを返します：0=COMPLETED、20=FAILED、21=CRASHED、22=SYSTEM_FAILURE、23=CANCELED、3=not-found、4=auth-error。Cobra アノテーション pp:typed-exit-codes を使えば、verify とエージェントが契約を直接読み取れます。

  エージェントが多数の実行を対象にシェルループを作成し、JSON を解析せずに成功／失敗を分岐したい場合に使用してください。

  trigger-dev-pp-cli runs get run_abc123 --json && echo COMPLETED || echo "$?"
  

コマンドリファレンス

batches — バッチを管理します

• trigger-dev-pp-cli batches <batchId> — IDでバッチを取得します。ステータスと、バッチ内のすべての実行のIDも含まれます。

deployments — デプロイを管理します

• trigger-dev-pp-cli deployments get-latest-v1 — 認証済みプロジェクトの最新の未管理デプロイに関する情報を取得します。
• trigger-dev-pp-cli deployments get-v1 — IDを指定して、特定のデプロイに関する情報を取得します。
• trigger-dev-pp-cli deployments list-v1 — 認証済み環境のデプロイを、新しいものから順に一覧表示します。

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

query — クエリを管理します

• trigger-dev-pp-cli query execute-v1 — 実行データに対してTRQL（Trigger.dev Query Language）クエリを実行します。TRQLはSQL形式のクエリ言語で、...
• trigger-dev-pp-cli query get-schema-v1 — TRQLクエリのスキーマを取得します。利用可能なすべてのテーブル、その列、データ型、説明などが含まれます。
• trigger-dev-pp-cli query list-dashboards-v1 — ウィジェットを備えた、利用可能な組み込みダッシュボードを一覧表示します。各ダッシュボードには、一般的な用途向けの事前構築済みTRQLクエリが含まれています...

queues — キューを管理します

• trigger-dev-pp-cli queues list-v1 — ページネーションに対応した、環境内のすべてのキューを一覧表示します。
• trigger-dev-pp-cli queues retrieve-v1 — ID、またはタイプと名前を指定してキューを取得します。

runs — 実行を管理します

• trigger-dev-pp-cli runs list-v1 — 特定の環境の実行を一覧表示します。ステータス、作成日時、タスク識別子、バージョンなどで絞り込めます。
• trigger-dev-pp-cli runs retrieve-v1 — ステータス、ペイロード、出力、試行回数など、実行に関する情報を取得します。認証方法が...の場合は、

schedules — スケジュールを管理します

• trigger-dev-pp-cli schedules create-v1 — 指定したオプションに基づいて、新しいIMPERATIVEスケジュールを作成します。
• trigger-dev-pp-cli schedules delete-v1 — IDでスケジュールを削除します。ダッシュボードまたは...で作成されたIMPERATIVEスケジュールのみが対象です。
• trigger-dev-pp-cli schedules get-v1 — IDでスケジュールを取得します。
• trigger-dev-pp-cli schedules list-v1 — すべてのスケジュールを一覧表示します。結果のページネーションも可能です。
• trigger-dev-pp-cli schedules update-v1 — IDでスケジュールを更新します。ダッシュボードまたは...で作成されたIMPERATIVEスケジュールのみが対象です。

tasks — タスクを管理します

• trigger-dev-pp-cli tasks — SDK 4.3.1以降では最大1,000件（以前のバージョンでは500件）のペイロードでタスクを一括トリガーします。

timezones — タイムゾーンを管理します

• trigger-dev-pp-cli timezones — スケジュールタスクでサポートされているすべてのタイムゾーンを取得します。

waitpoints — ウェイトポイントを管理します

• trigger-dev-pp-cli waitpoints complete-token-callback-v1 — トークンの...時にurlフィールドで返される、事前署名済みコールバックURLを使用してウェイトポイントトークンを完了します。
• trigger-dev-pp-cli waitpoints complete-token-v1 — ウェイトポイントトークンを完了し、wait.forToken()でそのトークンを待機している実行のブロックを解除します。任意のdata...
• trigger-dev-pp-cli waitpoints create-token-v1 — 外部イベントによって完了するまで実行を一時停止するために使用できる、新しいウェイトポイントトークンを作成します。トークン...
• trigger-dev-pp-cli waitpoints list-tokens-v1 — 現在の環境のウェイトポイントトークンを、ページネーション形式で一覧表示します。結果は作成日時の順に並びます...
• trigger-dev-pp-cli waitpoints retrieve-token-v1 — IDでウェイトポイントトークンを取得します。完了している場合は、現在のステータスと出力も含まれます。

適切なコマンドを見つける

実行したい操作は分かっていても、どのコマンドを使えばよいか分からない場合は、CLIに直接尋ねてください。

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

whichは、自然言語での機能に関する問い合わせを、このCLIの厳選された機能インデックスから最適なコマンドに対応付けます。終了コード0は少なくとも1つの候補が見つかったことを意味し、終了コード2は確信の持てる候補がないことを意味します。その場合は--helpに切り替えるか、より具体的な問い合わせを使用してください。

レシピ

本日の失敗をトリアージする

trigger-dev-pp-cli sync --resources runs --since 1d && trigger-dev-pp-cli failures top --since 1d --top 10 --agent --select 'task,error_signature,count,last_seen'

本日の実行を同期し、タスク別および正規化されたエラーシグネチャ別にグループ化して、主な失敗パターンを明らかにします。

デプロイ中の実行を監視する

trigger-dev-pp-cli runs watch --task my-task --notify --sound

デプロイ中もターミナルで監視します。新しい FAILED 実行が初めて発生すると、コマンドはゼロ以外の終了コードで終了し、ビープ音が鳴ります。

環境間の環境変数の差異を監査する

trigger-dev-pp-cli envvars diff --project proj_abc --from prod --to staging --agent

2 つの環境の変数を比較します。値はマスクされ、差異が示されます。

特定のエラーが発生した実行を検索する

trigger-dev-pp-cli runs find "connection timeout" --since 7d --status FAILED --agent --select 'id,taskIdentifier,error.message,createdAt'

--select を使ってエージェントのコンテキストを必要なフィールドに絞り込みながら、ローカルストアを部分文字列で検索します。

厳選された TRQL レシピを実行する

trigger-dev-pp-cli query run cost-by-model-7d --param env=prod --agent

SQL を作成せずに、厳選された TRQL クエリを実行します。レシピでは、一般的なディメンション別に失敗率、コスト、レイテンシを確認できます。

認証の設定

認証には、Authorization: Bearer ヘッダーで Trigger.dev シークレットキーを使用します。TRIGGER_SECRET_KEY に環境のキーを設定してください。開発環境では tr_dev_…、本番環境では tr_prod_…、個人用アクセストークンでは tr_pat_… を使用します。各キーは環境ごとにスコープが設定されており、開発用キーで本番環境の実行を管理することはできません。

trigger-dev-pp-cli doctor を実行して、設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加します。これは --json --compact --no-input --no-color --yes に展開されます。

• パイプ処理可能 — JSON は stdout に、エラーは stderr に出力されます

• フィルタリング可能 — --select でフィールドの一部を選択します。ドット区切りパスはネストされた構造をたどり、配列では各要素をたどります。詳細な API でコンテキストを小さく保つために重要です。

  trigger-dev-pp-cli batches mock-value --agent --select id,name,status
  

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

• オフラインで利用可能 — 同期／検索コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

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

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

レスポンスエンベロープ

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

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

データには .results を、ライブかローカルかの確認には .meta.source を解析してください。人間が読みやすい N results (live) という概要は、stdout がターミナルの場合にのみ stderr に出力されます。パイプやエージェントで利用する場合、stdout には純粋な JSON が出力されます。

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

この CLI について気になる点に気づいた場合（エージェントが気づいた場合も含む）、記録してください。

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

エントリはローカルの ~/.trigger-dev-pp-cli/feedback.jsonl に保存されます。TRIGGER_DEV_FEEDBACK_ENDPOINT が設定されていて、さらに --send が渡された場合、または TRIGGER_DEV_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」パターンです。

trigger-dev-pp-cli profile save briefing --json
trigger-dev-pp-cli --profile briefing batches mock-value
trigger-dev-pp-cli profile list --json
trigger-dev-pp-cli profile show briefing
trigger-dev-pp-cli profile delete briefing --yes

明示的なフラグは常にプロファイル値より優先され、プロファイル値はデフォルト値より優先されます。agent-context は、利用可能なすべてのプロファイルを available_profiles に一覧表示するため、情報を調べるエージェントは実行時にプロファイルを検出できます。

終了コード

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

引数の解析

$ARGUMENTS を解析します：

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

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

1. MCP サーバーをインストールします：

   go install github.com/mvanhorn/printing-press-library/library/developer-tools/trigger-dev/cmd/trigger-dev-pp-mcp@latest
   

2. Claude Code に登録します：

   claude mcp add trigger-dev-pp-mcp -- trigger-dev-pp-mcp
   

3. 確認します：claude mcp list

直接使用

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

   trigger-dev-pp-cli <command> [subcommand] [args] --agent
   

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