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 的方式取决于用户的需求——按用户的意愿来，不要默认采用某种模式。

• 用户态度坚决／“直接帮我设置好”／“去做吧” → 由你从头到尾全程处理。 在自己的 shell 中运行下方的顺利流程代码块，读取 --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	安装、二进制文件、登录设备流程，以及从头到尾创建第一个项目。包含 Agent 快速入门——非交互式、可脚本化的设置流程。
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。