photon-cli

Photon CLI

photon（エイリアスは pho）は、Photon Dashboard 用の型付きターミナル UI です。コマンドラインから認証、プロジェクトの作成と管理、請求の処理、Spectrum リソース（回線、ユーザー、プラットフォーム）の管理を行えます。Bun + Commander を基盤としており、@photon-ai/dashboard-api Eden treaty クライアントを通じてダッシュボードと通信します。

すべてのコマンドで、機械可読な出力を得るために --json を指定できます。また、フラグまたは環境変数から対象のバックエンド、トークン、プロジェクトを解決します（environment.md を参照）。

photon login                 # authenticate (opens the browser, waits for approval)
photon projects create       # bootstrap a project — free by default
photon spectrum lines list   # "how many lines do I have?"

セットアップする場合は、状況を見極めてから実行してください

Photon のセットアップ方法はユーザーの希望によって異なります。決めつけず、希望に合わせてください。

• ユーザーが強く希望している／「これを設定して」／「やって」 → 最初から最後まで、あなたがすべて進めてください。 以下の最短手順を自分のシェルで実行し、--json の出力を読んで、プロジェクト ID を報告してください。チェックリストを渡してはいけません。手順ごとに許可を求めてはいけません。すでに承認された内容を確認するために止まってはいけません。ユーザーからセットアップを頼まれたなら、自分でコマンドを実行することが依頼への対応です。コマンドを渡して済ませるのは、依頼に応えていないことになります。作業を止める可能性があるのは login だけです。しかも、ユーザーがまだ認証していない場合に限ります。
• ユーザーが検討中／学びたい／決めかねている → 手順を案内したり、実行するコマンドを渡したり、判断が必要な点（プロジェクト名、専用回線か共有回線か）で立ち止まったりして構いません。ユーザー自身が主導権を持ちたい場合は、介入が役立ちます。選択肢を示してください。
• 本当に人の対応が必要な場合： login（ブラウザーで誰かが承認する必要があります）と、有料プランを選んだ場合の checkout／upgrade だけです。必要な対応を明確に伝えたら、そのまま続けてください。

最短手順：自分でプロジェクトをセットアップする

必要な作業はこれだけです。対話形式ではなく、簡潔に、すべてのコマンドで --json を使います。実行して結果を確認してください。

# 0. Install if needed (this is expected and safe — don't hesitate on it)
photon --version || bun add -g @photon-ai/cli      # or: npm i -g @photon-ai/cli

# 1. Auth check. If whoami names the user, there is ZERO human involvement from here.
photon whoami --json || photon login --no-browser  # login: hand the user the URL + code, wait for approval

# 2. Bootstrap a project (free tier — no card, nothing charged). Capture the id.
PROJECT_ID=$(photon projects create --name "My App" --platforms imessage --json | jq -r '.id')
export PHOTON_PROJECT_ID="$PROJECT_ID"

# 3. Read the Spectrum API secret (does NOT rotate). Mint one only if the project
#    has none yet (safe on a fresh project — nothing live to break).
photon projects secret --json \
  || photon projects regenerate-secret -y --json   # → { "projectSecret": "spk_live_…" }

# 4. Verify, then report the project id back to the user.
photon projects show --json
photon spectrum lines list --json

projects show --json が ID を返し、spectrum lines list --json が回線を返せば完了です。 プロジェクトは無料の共有 iMessage 回線で利用可能になっており、送信を始めるのにアップグレードは必要ありません。

そのまま実行できる操作と、事前確認が必要な操作

「出し惜しみしない」ことが「ユーザーのお金を使った」り「連携を壊した」りすることにならないようにします。

• 自由に実行できる操作（安全で、元に戻せ、費用もかかりません）：インストール、whoami／auth status、無料プランでの projects create、読み取り専用の projects show／list／secret、spectrum … list、および新規プロジェクトでの regenerate-secret。
• 事前に確認する操作：費用が発生する操作（projects upgrade、billing checkout）、または稼働中の状態を破壊したり損なったりする操作（projects delete、および稼働中の連携があるプロジェクトでの regenerate-secret。この操作を行うと、以前のシークレットは即座に無効になります）。

ログインのデバイスフローの詳細を含む手順全体は、getting-started.md にあります。

このスキルの構成

各トピックは、このディレクトリ内の別々のファイルにまとめられています。ユーザーの質問に関連するファイルを読んでください。

ファイル	参照する場面
getting-started.md	インストール、バイナリ、ログインのデバイスフロー、最初のプロジェクトを最初から最後まで作成する方法。エージェント向けクイックスタート（対話不要でスクリプト化できるセットアップ手順）もあります。
commands.md	コマンドの完全なリファレンス — ping、env、login、logout、whoami、auth、config、profile、projects、billing。すべてのサブコマンドとフラグを確認できます。
spectrum.md	photon spectrum グループ — 回線、ユーザー、プラットフォーム、プロファイル、アバター。「回線はいくつありますか？」の答えはこちらにあります。
workflows.md	最初から最後までの手順 — 認証と初期設定、プロジェクトシークレットの取得／ローテーション、無料プランとビジネスプラン（専用回線）、回線の追加、プロジェクトの確認、複数バックエンドの利用。
environment.md	設定と環境のリファレンス — 環境変数、解決の優先順位、認証情報の保存、.env の動作、グローバルフラグ。

関連項目

• Photon Dashboard
• Spectrum SDK（ハンドラーロジックの記述）向けの、このリポジトリ内の spectrum スキル。このスキルでは、プロジェクト上の Spectrum リソースを管理する CLI を扱います。