TrayPage

TrayPage CLI のインストール、OAuth 認証、投稿、レビュー待機、コメント反映の使い方。

TrayPage CLI は、MCP を使えない環境やスクリプトから TrayPage にページを投稿するためのコマンドラインツールです。AI エージェントは CLI をプロセスとして実行し、ブラウザ上のレビュー完了を待ってから次の修正に進めます。

MCP を使える AI ツールでは MCP 連携を推奨します。CLI は MCP がない環境、CI、ローカルスクリプト、または WebSocket でレビュー完了を待つワークフローに向いています。

インストール

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

npm install -g @traypage/cli

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

traypage --help

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

pnpm traypage -- --help

認証

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

traypage auth login
traypage auth status

CLI は短命の access token と refresh token を ~/.config/traypage/config.json に保存します。OAuth は consent 画面で organization と project 範囲を選んで許可できるため、人が使う CLI では OAuth を推奨します。

CI やブラウザを開けない自動化では、TrayPage API token（tp_ で始まる token）も使えます。API token は project に紐づくため、TrayPage の project settings にある MCP / API連携 から発行します。

traypage auth token set tp_xxx

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

TRAYPAGE_API_TOKEN=tp_xxx traypage pages list

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

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

profile を切り替える

複数の organization / project を使う場合は profile を作ります。profile には既定の organization、project、API base URL、必要に応じて OAuth login や API token を保存できます。

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

以後 prod が current profile になり、投稿先を毎回指定しなくても acme / reports が使われます。

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

profile 名をその場で渡すこともできます。

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

CI や複数 terminal では環境変数でも切り替えられます。

TRAYPAGE_PROFILE=prod traypage pages list

profile の確認と切り替え:

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

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

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

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

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

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

version を公開する

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

traypage versions publish --page page_xxx --version 2

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

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 エージェントに渡す修正指示としてまとめたい場合は revision prompt を取得します。

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

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

レビュー完了を待つ

AI エージェントがページを投稿したあと、ユーザーがブラウザでレビューし、完了ボタンを押したタイミングでエージェントを再開させるには review session を使います。

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

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

長時間待つ場合や、いったん terminal を閉じたい場合は、session を作成してからあとで再開できます。

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

同じ machine では watch token が CLI config に保存されるため、通常は resume に session ID だけ渡せば足ります。別の machine や CI で再開する場合は --watch-token trs_xxx を渡します。

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

よく使う環境変数

変数	説明
`TRAYPAGE_API_TOKEN`	CI/非対話用の `tp_` API token。OAuth config より優先されます
`TRAYPAGE_API_BASE_URL`	API origin。ローカル開発やステージングで使います
`TRAYPAGE_PROFILE`	使用する profile 名。`--profile` がある場合はそちらが優先されます
`TRAYPAGE_ORGANIZATION`	既定の organization slug
`TRAYPAGE_PROJECT`	既定の project slug

トラブルシューティング

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

CLI

On this page