TrayPage

ブラウザでレビュー完了したら AI エージェントを再開し、コメントを次の版へ反映するための CLI。

TrayPage CLI は、コーディングエージェントとブラウザレビューをつなぐためのコマンドラインツールです。AI エージェントがページを投稿して traypage review start --watch で待機し、レビュアーがブラウザでレビュー完了を通知すると、CLI が未解決コメント、修正指示、次に実行すべきコマンドを返します。エージェントはその結果を読んで、コメントを反映した次のバージョンを投稿できます。

MCP を使えない環境、CI、ローカルスクリプトからページを投稿したい場合にも CLI を使えます。MCP を使える AI ツールでは MCP 連携が通常の入口ですが、レビュー完了までプロセスを待機させてそのまま修正に進ませたい場合は CLI のレビューセッションが向いています。

レビュー完了で AI エージェントを再開する

典型的な流れは次の通りです。

AI エージェントが HTML / Markdown を作り、CLI で TrayPage に下書きバージョンを投稿する
AI エージェントが traypage review start --page page_xxx --version 1 --watch を実行し、レビュー完了を待つ
レビュアーがブラウザでページを確認し、コメントや補足メモを付けてレビュー完了を通知する
CLI が approved、未解決コメント数、修正指示、次に実行すべきコマンドを出力する
AI エージェントがその出力を使い、コメントを反映した新しいバージョンを投稿する

この流れでは、レビュアーはブラウザ上で完了操作をするだけです。修正指示を手でコピーしてチャットに貼り直す必要はありません。コピー用の修正指示は、待機中の CLI がない場合や手動で修正指示を渡したい場合の補助導線として使えます。

インストール

Node.js 22 以上を用意し、npm から CLI をインストールします。

npm install -g @traypage/cli

インストール後、traypage --help が表示されることを確認します。

traypage --help

ローカル開発でこのリポジトリ内の CLI を使う場合は、npm package ではなく次の形で同じコマンドを実行できます。

pnpm traypage -- --help

認証

通常は OAuth でログインします。CLI がブラウザを開き、MCP と同じ認可画面でワークスペース、アクセス可能なプロジェクト、既定プロジェクトを選びます。トークンを手でコピーする必要はありません。

traypage auth login
traypage auth status

CLI は短命のアクセストークンと更新用トークンを ~/.config/traypage/config.json に保存します。OAuth は認可画面でワークスペースとプロジェクト範囲を選んで許可できるため、人が使う CLI では OAuth を推奨します。

CI やブラウザを開けない自動化では、TrayPage API トークン（tp_ で始まるトークン）も使えます。API トークンはプロジェクトに紐づくため、TrayPage のプロジェクト設定にある MCP / API連携 から発行します。

traypage auth token set tp_xxx

一時実行では、ファイルに保存せず環境変数でも渡せます。

TRAYPAGE_API_TOKEN=tp_xxx traypage pages list

ローカル環境やステージングを使う場合は接続先 URL を指定します。OAuth と API トークンのどちらでも同じ指定を使えます。

traypage auth login --api-base-url http://localhost:3000
traypage auth token set tp_xxx --api-base-url http://localhost:3000

または実行時に指定します。

TRAYPAGE_API_BASE_URL=http://localhost:3000 traypage pages list

プロファイルを切り替える

複数のワークスペースやプロジェクトを使う場合はプロファイルを作ります。プロファイルには既定のワークスペース、プロジェクト、接続先 URL、必要に応じて OAuth ログインや API トークンを保存できます。

traypage profiles set prod --organization acme --project reports --use
traypage auth login --profile prod

以後 prod が現在のプロファイルになり、投稿先を毎回指定しなくても acme / reports が使われます。

traypage publish ./report.html --title "売上分析レポート"

プロファイル名をその場で渡すこともできます。

traypage publish ./report.html --profile prod
traypage pages list --profile prod

CI や複数のターミナルでは環境変数でも切り替えられます。

TRAYPAGE_PROFILE=prod traypage pages list

プロファイルの確認と切り替え:

traypage profiles list
traypage profiles show prod
traypage profiles use prod
traypage profiles remove prod

ページを投稿する

HTML または Markdown ファイルから新しいページを作成します。

traypage publish ./report.html \
  --title "売上分析レポート" \
  --organization acme \
  --project reports

投稿された最初のバージョンは下書きです。レビュー URL と共有 URL が返りますが、共有 URL に本文を出すにはバージョンを公開する必要があります。

すぐ共有 URL に表示したい場合は --publish を付けます。

traypage publish ./report.html --title "売上分析レポート" --publish

既存ページに新しい下書きバージョンを追加するには --page を指定します。

traypage publish ./report-v2.html --page page_xxx --changelog "レビューコメントを反映"

ページを整理する

現在のプロファイルやトークンのプロジェクトにあるページを一覧します。アーカイブ済みページを確認する場合は --archived を付けます。

traypage pages list
traypage pages list --archived

ページをアーカイブすると通常の一覧から隠れ、アクティブページ数の枠が空きます。本文やバージョンは削除されません。

traypage pages archive --page page_xxx
traypage pages unarchive --page page_xxx

復元するとアクティブページ数の枠を消費するため、プラン上限に達している場合は失敗します。

バージョンを公開する

共有 URL に表示するバージョンを切り替えます。この操作は公開範囲を変更しません。

traypage versions publish --page page_xxx --version 2

公開範囲を変更する場合は visibility コマンドを使います。

次の値は CLI に渡すための正確な指定です。画面上では「プロジェクトメンバー」「リンクを知っている全員」と表示されます。

traypage visibility set --page page_xxx --visibility project_members
traypage visibility set --page page_xxx --visibility public_link

コメントを取得する

未解決コメントを JSON で取得します。

traypage comments list --page page_xxx --version 2 --json

AI エージェントに渡す修正指示としてまとめたい場合は、コメントから修正指示を取得します。

traypage comments prompt --page page_xxx --version 2 --language ja

修正指示は未解決コメントを単純な修正リストとして扱いません。質問コメントのように、ファイル変更ではなく回答が適切な項目も AI エージェントに伝えます。

レビュー完了を待つ

AI エージェントをブラウザレビュー完了後に自動再開させるにはレビューセッションを使います。

traypage review start --page page_xxx --version 2 --watch

--watch を付けると CLI は WebSocket で TrayPage に接続し、レビュー完了まで待機します。ユーザーが画面でレビューを完了すると、CLI は approved、未解決コメント数、修正指示、次に実行すべきコマンドを含む結果を出力します。AI エージェントはその出力を読んで次の修正に進めます。

長時間待つ場合や、いったんターミナルを閉じたい場合は、セッションを作成してからあとで再開できます。

traypage review start --page page_xxx --version 2 --json
traypage review resume revs_xxx

同じ端末では待機用トークンが CLI 設定に保存されるため、通常は resume にセッション ID だけ渡せば足ります。別の端末や CI で再開する場合は --watch-token trs_xxx を渡します。

レビュー画面から完了を通知する操作は、ページ本文やコメントの保存とは別です。未解決コメントと補足メモをまとめて AI エージェントに渡し、待機中の AI エージェントが結果を受け取り次の修正に進みます。

よく使う環境変数

変数	説明
`TRAYPAGE_API_TOKEN`	CI/非対話用の `tp_` API トークン。OAuth 設定より優先されます
`TRAYPAGE_API_BASE_URL`	接続先 URL。ローカル開発やステージングで使います
`TRAYPAGE_PROFILE`	使用するプロファイル名。`--profile` がある場合はそちらが優先されます
`TRAYPAGE_ORGANIZATION`	既定のワークスペース ID
`TRAYPAGE_PROJECT`	既定のプロジェクト ID

トラブルシューティング

Authentication required — traypage auth status で OAuth ログインが済んでいるか確認してください。人が使う端末では traypage auth login、CI では TRAYPAGE_API_TOKEN を設定します。
Project not found / project_restricted — API トークンは発行したプロジェクト専用です。別プロジェクトに投稿するには、そのプロジェクトのトークンを発行するか、--organization と --project が正しいか確認してください。
WebSocket がつながらない — traypage review start --watch は WebSocket を使います。接続できない場合でも CLI は結果確認にフォールバックします。あとから traypage review resume revs_xxx で結果を取得できます。
投稿できるがコメントを取得できない — トークンのスコープに comment:read と revision_prompt:read が含まれているか確認してください。
ローカル開発で本番環境に接続してしまう — TRAYPAGE_API_BASE_URL=http://localhost:3000 を指定するか、traypage auth token set ... --api-base-url http://localhost:3000 で保存してください。

CLI

On this page