### Install Dependencies and Generate Docs

Source: https://github.com/photon-hq/docs/blob/main/README.md

Install project dependencies, generate documentation files from source, and start a local development server for previewing. Ensure you are in the repository root.

```bash
pnpm install
pnpm docs:generate         # vellum: .mdx.vel -> .mdx
mint dev                   # preview at http://localhost:3000
```

--------------------------------

### Install Hono and run server

Source: https://github.com/photon-hq/docs/blob/main/webhooks/quickstart.mdx

Commands to install the Hono library and start the development server with hot-reloading.

```bash
bun add hono
bun --hot server.ts
```

--------------------------------

### Install Photon CLI globally with Bun

Source: https://github.com/photon-hq/docs/blob/main/cli/installation.mdx

Install the Photon CLI globally using Bun for daily use, ensuring `photon` is available on your PATH.

```shell
bun add -g @photon-ai/cli
```

--------------------------------

### Install Mintlify CLI

Source: https://github.com/photon-hq/docs/blob/main/CONTRIBUTING.md

Install the Mintlify CLI globally to enable local documentation development. This command is run in your terminal.

```bash
npm i -g mint
```

--------------------------------

### Install and Login to Photon CLI

Source: https://github.com/photon-hq/docs/blob/main/cli/overview.mdx

Install the Photon CLI globally and log in to authenticate your device. The login command will open a browser for approval.

```sh
npx @photon-ai/cli login
```

```sh
photon login
```

--------------------------------

### Install Mintlify Skill

Source: https://github.com/photon-hq/docs/blob/main/AGENTS.md

Add the Mintlify skill to your project to access product knowledge and features. This command installs the skill from the provided URL.

```bash
npx skills add https://mintlify.com/docs
```

--------------------------------

### Verify Photon CLI installation

Source: https://github.com/photon-hq/docs/blob/main/cli/installation.mdx

Confirm the Photon CLI is installed correctly by checking its version and running a basic connectivity test.

```shell
photon --version
photon ping
```

--------------------------------

### Install Photon CLI globally with npm

Source: https://github.com/photon-hq/docs/blob/main/cli/installation.mdx

Install the Photon CLI globally using npm for daily use, ensuring `photon` is available on your PATH.

```shell
npm install -g @photon-ai/cli
```

--------------------------------

### Install Photon CLI globally with Yarn

Source: https://github.com/photon-hq/docs/blob/main/cli/installation.mdx

Install the Photon CLI globally using Yarn for daily use, ensuring `photon` is available on your PATH.

```shell
yarn global add @photon-ai/cli
```

--------------------------------

### Install Photon CLI globally with pnpm

Source: https://github.com/photon-hq/docs/blob/main/cli/installation.mdx

Install the Photon CLI globally using pnpm for daily use, ensuring `photon` is available on your PATH.

```shell
pnpm add -g @photon-ai/cli
```

--------------------------------

### Run Mintlify Development Server

Source: https://github.com/photon-hq/docs/blob/main/AGENTS.md

Preview your documentation site locally by running this command. It starts a development server that reflects changes in real-time.

```bash
mint dev
```

--------------------------------

### Install Photon CLI with Homebrew

Source: https://github.com/photon-hq/docs/blob/main/cli/installation.mdx

Use Homebrew to install the Photon CLI on macOS or Linux for a self-contained binary. Updates are handled by `brew upgrade`.

```shell
brew install photon-hq/photon/photon
photon login
```

--------------------------------

### Download and install Photon CLI standalone binary

Source: https://github.com/photon-hq/docs/blob/main/cli/installation.mdx

Download a prebuilt binary directly for environments without runtime dependencies like CI. Ensure to set execute permissions.

```shell
# <os>: darwin | linux
# <arch>: arm64 | x64
curl -L -o /usr/local/bin/photon \
  https://github.com/photon-hq/cli/releases/latest/download/photon-<os>-<arch>
chmod +x /usr/local/bin/photon
photon --version
```

```shell
curl -L -o /usr/local/bin/photon \
  https://github.com/photon-hq/cli/releases/latest/download/photon-darwin-arm64
chmod +x /usr/local/bin/photon
```

--------------------------------

### Authentication Example

Source: https://github.com/photon-hq/docs/blob/main/api-reference/introduction.mdx

Demonstrates how to authenticate API requests using project ID and project secret with HTTP Basic authentication.

```APIDOC
## Authentication Example

### Description

This example shows how to authenticate API requests using your `projectId` as the username and `projectSecret` as the password with HTTP Basic authentication.

### Method

`GET` (example, actual method depends on the endpoint)

### Endpoint

`https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/`

### Request Example

```sh
curl -u "$PROJECT_ID:$PROJECT_SECRET" \
  "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/"
```
```

--------------------------------

### Use the `pho` Alias

Source: https://github.com/photon-hq/docs/blob/main/cli/overview.mdx

After global installation, a `pho` shortcut is automatically created. Use it as a shorthand for `photon` commands.

```sh
pho projects ls
```

```sh
pho whoami
```

--------------------------------

### Get Project IDs with JSON Output

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Lists projects and extracts their IDs using JSON output and `jq` for parsing. Requires `--json` flag and `jq` to be installed.

```bash
photon projects ls --json | jq '.[] | .id'
```

--------------------------------

### Create a basic Hono server

Source: https://github.com/photon-hq/docs/blob/main/webhooks/quickstart.mdx

Set up a simple Hono server to listen for POST requests on the /spectrum-webhook endpoint. This is the initial setup before adding verification logic.

```typescript
import { Hono } from 'hono';

const app = new Hono();

app.post('/spectrum-webhook', async (c) => {
  const body = await c.req.text();
  console.log('received', body.slice(0, 200));
  return c.text('ok', 200);
});

export default { port: 3000, fetch: app.fetch };
```

--------------------------------

### Create a Project Interactively

Source: https://github.com/photon-hq/docs/blob/main/cli/projects.mdx

Creates a new project. Without flags, the CLI initiates an interactive prompt to guide you through the creation process.

```sh
photon projects create
```

--------------------------------

### Display Alternative Code Examples with Tabs

Source: https://github.com/photon-hq/docs/blob/main/CLAUDE.md

Use the Tabs and Tab components to show the same task implemented in multiple ways, such as plain text versus with options.

```mdx
<Tabs>
  <Tab title="Plain text">
    ```ts
    await im.messages.send(chat, "Hello!");
    ```
  </Tab>
  <Tab title="With options">
    ...
  </Tab>
</Tabs>
```

--------------------------------

### Example server output for a message

Source: https://github.com/photon-hq/docs/blob/main/webhooks/quickstart.mdx

The expected console output when your webhook successfully receives and processes a 'messages' event.

```text
message from +15550100 : { type: 'text', text: 'hi' }
```

--------------------------------

### Example Webhook POST Request

Source: https://github.com/photon-hq/docs/blob/main/webhooks/overview.mdx

This is an example of a POST request that Spectrum would send to your registered webhook URL. It includes essential headers for event identification and signature verification.

```http
POST https://your-app.com/spectrum-webhook
X-Spectrum-Event: messages
X-Spectrum-Signature: v0=<hmac>
X-Spectrum-Timestamp: 1747242392

{"event":"messages","space":{...},"message":{...}}
```

--------------------------------

### Verify Webhook Signature with Go + net/http

Source: https://github.com/photon-hq/docs/blob/main/webhooks/verifying-signatures.mdx

This Go example shows how to verify webhook signatures using the standard net/http package. It includes checks for timestamp validity and signature correctness.

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
	"os"
	"strconv"
	"time"
)

var secret = []byte(os.Getenv("SPECTRUM_SIGNING_SECRET"))

const toleranceSec = 5 * 60

func handleWebhook(w http.ResponseWriter, r *http.Request) {
	rawBody, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "read failed", 400)
		return
	}

	timestamp := r.Header.Get("X-Spectrum-Timestamp")
	signature := r.Header.Get("X-Spectrum-Signature")
	if timestamp == "" || signature == "" {
		http.Error(w, "missing headers", 400)
		return
	}

	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		http.Error(w, "invalid timestamp", 400)
		return
	}
	if abs(time.Now().Unix()-ts) > toleranceSec {
		http.Error(w, "stale timestamp", 400)
		return
	}

	mac := hmac.New(sha256.New, secret)
	mac.Write([]byte("v0:" + timestamp + ":" + string(rawBody)))
	expected := "v0=" + hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(expected), []byte(signature)) {
		http.Error(w, "bad signature", 401)
		return
	}

	w.WriteHeader(200)
	w.Write([]byte("ok"))
}

func abs(x int64) int64 { if x < 0 { return -x }; return x }
```

--------------------------------

### Build heif2jpeg from source

Source: https://github.com/photon-hq/docs/blob/main/utilities/heif2jpeg.mdx

To build the heif2jpeg library from source, clone the repository, install dependencies, and use the napi build command. This process requires Rust, CMake, and a C/C++ compiler.

```bash
git clone --recurse-submodules https://github.com/photon-hq/heif2jpeg.git
cd heif2jpeg
npm install
npx napi build --platform --release
npm test
```

--------------------------------

### Install heif2jpeg with npm, pnpm, yarn, or bun

Source: https://github.com/photon-hq/docs/blob/main/utilities/heif2jpeg.mdx

Choose your preferred package manager to install the heif2jpeg library. This package provides prebuilt binaries for various platforms.

```bash
npm install heif2jpeg
```

```bash
pnpm add heif2jpeg
```

```bash
yarn add heif2jpeg
```

```bash
bun add heif2jpeg
```

--------------------------------

### Verify Webhook Signature with Node.js + Express

Source: https://github.com/photon-hq/docs/blob/main/webhooks/verifying-signatures.mdx

This Node.js and Express example demonstrates how to verify incoming webhook signatures. Ensure the SPECTRUM_SIGNING_SECRET environment variable is set.

```javascript
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const app = express();
const SECRET = process.env.SPECTRUM_SIGNING_SECRET;
const TOLERANCE_SEC = 5 * 60;

app.post(
  '/spectrum-webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body.toString('utf8');
    const timestamp = req.header('X-Spectrum-Timestamp');
    const signature = req.header('X-Spectrum-Signature');

    if (!timestamp || !signature) return res.status(400).send('missing headers');

    const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
    if (!Number.isFinite(age) || age > TOLERANCE_SEC) {
      return res.status(400).send('stale timestamp');
    }

    const expected =
      'v0=' +
      createHmac('sha256', SECRET)
        .update(`v0:${timestamp}:${rawBody}`)
        .digest('hex');

    const a = Buffer.from(expected);
    const b = Buffer.from(signature);
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
      return res.status(401).send('bad signature');
    }

    const payload = JSON.parse(rawBody);
    handleEvent(req.header('X-Spectrum-Event'), payload);
    return res.status(200).send('ok');
  },
);

app.listen(3000);
```

--------------------------------

### Run Photon CLI commands on demand

Source: https://github.com/photon-hq/docs/blob/main/cli/installation.mdx

Execute CLI commands without a global installation using package runners like npx, pnpx, or bunx. This automatically fetches the latest release and is suitable for scripts or testing.

```shell
npx @photon-ai/cli login
npx @photon-ai/cli projects ls
```

```shell
pnpx @photon-ai/cli login
pnpx @photon-ai/cli projects ls
```

```shell
bunx @photon-ai/cli login
bunx @photon-ai/cli projects ls
```

--------------------------------

### Verify Webhook Signature with Python + FastAPI

Source: https://github.com/photon-hq/docs/blob/main/webhooks/verifying-signatures.mdx

This Python example uses FastAPI to verify webhook signatures. It checks the timestamp and signature against the configured secret.

```python
import hashlib, hmac, json, os, time
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()
SECRET = os.environ["SPECTRUM_SIGNING_SECRET"].encode()
TOLERANCE_SEC = 5 * 60


@app.post("/spectrum-webhook")
async def spectrum_webhook(
    request: Request,
    x_spectrum_event: str = Header(None),
    x_spectrum_timestamp: str = Header(None),
    x_spectrum_signature: str = Header(None),
):
    raw_body = await request.body()

    if not x_spectrum_timestamp or not x_spectrum_signature:
        raise HTTPException(400, "missing headers")

    try:
        age = abs(int(time.time()) - int(x_spectrum_timestamp))
    except ValueError:
        raise HTTPException(400, "invalid timestamp")
    if age > TOLERANCE_SEC:
        raise HTTPException(400, "stale timestamp")

    base = f"v0:{x_spectrum_timestamp}:{raw_body.decode('utf-8')}".encode()
    expected = "v0=" + hmac.new(SECRET, base, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, x_spectrum_signature):
        raise HTTPException(401, "bad signature")

    handle_event(x_spectrum_event, json.loads(raw_body))
    return {"ok": True}
```

--------------------------------

### Initiate a Stripe Checkout Session

Source: https://github.com/photon-hq/docs/blob/main/cli/billing.mdx

Creates a Stripe Checkout session for subscribing to a plan and opens it in the browser. You can specify the quantity for the line item. Use `--no-browser` to print the URL or `--json` to get the session URL programmatically.

```sh
photon billing checkout --plan <price-id>
```

```sh
photon billing checkout --plan <price-id> --qty 5
```

--------------------------------

### Spectrum webhook registration response

Source: https://github.com/photon-hq/docs/blob/main/webhooks/quickstart.mdx

Example JSON response from registering a webhook, containing the webhook ID, URL, and the crucial signing secret.

```json
{
  "succeed": true,
  "data": {
    "id": "6a4d2e8c-7b1f-4d3a-9a8e-2c5d6f7e8a9b",
    "webhookUrl": "https://abcd1234.ngrok-free.app/spectrum-webhook",
    "signingSecret": "a3f8e29b...5c7e9b2d",
    "createdAt": "2026-05-14T19:00:00Z",
    "updatedAt": "2026-05-14T19:00:00Z"
  }
}
```

--------------------------------

### Webhook Delivery Success Example

Source: https://github.com/photon-hq/docs/blob/main/webhooks/delivery.mdx

A simple webhook handler that verifies the signature, enqueues the payload for asynchronous processing, and returns a 200 OK response immediately.

```typescript
app.post('/spectrum-webhook', async (c) => {
  if (!verify(c)) return c.text('bad signature', 401);

  const payload = JSON.parse(await c.req.text());
  void enqueueForProcessing(payload);

  return c.text('ok', 200);
});
```

--------------------------------

### List Webhooks using CLI Helper

Source: https://github.com/photon-hq/docs/blob/main/webhooks/managing-webhooks.mdx

A shell helper function to list webhooks for the active project using the Photon CLI and curl. It retrieves project credentials and makes a GET request to the webhooks endpoint.

```sh
# A small helper to list webhooks for the active project
list_webhooks() {
  local row creds id
  row=$(photon projects show --json)
  id=$(echo "$row" | jq -r '.id')
  creds=$(echo "$row" | jq -r '"\(.id):\(.secret)"')
```

--------------------------------

### Send a Plain Text Message

Source: https://github.com/photon-hq/docs/blob/main/CLAUDE.md

Basic example of sending a message using the im.messages.send function without any additional options.

```ts
await im.messages.send(chat, "Hello!");
```

--------------------------------

### Login to Photon CLI without Browser

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Use this command on headless machines (e.g., SSH sessions, containers) to get a login URL that can be opened on another device.

```bash
photon login --no-browser
```

--------------------------------

### Registering a New Webhook URL with ngrok

Source: https://github.com/photon-hq/docs/blob/main/webhooks/troubleshooting.mdx

When using free ngrok tunnels, the URL changes on each restart. This example shows how to obtain the new ngrok URL and register it with the Spectrum API using curl.

```bash
ngrok http 3000
# Copy the new URL, then:
curl -X POST "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/" \
  -u "$PROJECT_ID:$PROJECT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://NEW-URL.ngrok-free.app/spectrum-webhook"}'
```

--------------------------------

### Create a Project with Flags

Source: https://github.com/photon-hq/docs/blob/main/cli/projects.mdx

Creates a new project by specifying its name, location, and enabling Spectrum directly via command-line flags.

```sh
photon projects create --name "My Project" --location us-east --spectrum
```

--------------------------------

### Update Spectrum Profile

Source: https://github.com/photon-hq/docs/blob/main/cli/spectrum.mdx

Update fields of the Spectrum profile. For example, you can change the display name.

```sh
# Update profile fields
photon spectrum profile update --display-name "Support Bot"
```

--------------------------------

### Initialize Spectrum SDK

Source: https://github.com/photon-hq/docs/blob/main/webhooks/overview.mdx

This snippet shows how to initialize the Spectrum SDK. It's presented as a contrast to webhook usage, highlighting the loop that webhooks replace.

```typescript
const app = await Spectrum({ projectId, projectSecret, providers: [imessage.config()] });
// Without webhooks, you'd run this loop yourself, forever.
for await (const [space, message] of app.messages) { /* ... */ }
```

--------------------------------

### List Projects

Source: https://github.com/photon-hq/docs/blob/main/cli/projects.mdx

Lists all available projects. Use the --json flag for machine-readable output.

```sh
photon projects ls
photon projects ls --json
```

--------------------------------

### Add Spectrum User

Source: https://github.com/photon-hq/docs/blob/main/cli/spectrum.mdx

Add a new user to your project's Spectrum instance.

```sh
photon spectrum users add
```

--------------------------------

### Enable Spectrum Platform

Source: https://github.com/photon-hq/docs/blob/main/cli/spectrum.mdx

Enable a specific messaging platform for your project.

```sh
photon spectrum platforms enable <platform-name>
```

--------------------------------

### Show Current Photon Environment

Source: https://github.com/photon-hq/docs/blob/main/cli/profile-and-utilities.mdx

Prints the currently resolved backend, confirming which backend your commands will target. Useful when using PHOTON_API_HOST.

```sh
photon env current
```

--------------------------------

### Show Photon Config

Source: https://github.com/photon-hq/docs/blob/main/cli/profile-and-utilities.mdx

Dumps the active CLI configuration, including the config directory path, current backend, active PHOTON_PROJECT_ID, and relevant environment variable values. Does not include secrets.

```sh
photon config show
```

```sh
photon config show --json
```

--------------------------------

### Open Project in Dashboard

Source: https://github.com/photon-hq/docs/blob/main/cli/projects.mdx

Opens the project's Dashboard page in your default web browser. If no project ID is specified, it defaults to the project ID from the PHOTON_PROJECT_ID environment variable. Use --no-browser to print the URL instead of opening it.

```sh
photon projects open
photon projects open <project-id>
photon projects open --no-browser   # prints the URL instead
```

--------------------------------

### Show Project Details

Source: https://github.com/photon-hq/docs/blob/main/cli/projects.mdx

Displays details for a specific project. If no project ID is provided, it defaults to the project ID set in the PHOTON_PROJECT_ID environment variable.

```sh
photon projects show
photon projects show <project-id>
```

--------------------------------

### Upload Spectrum Avatar

Source: https://github.com/photon-hq/docs/blob/main/cli/spectrum.mdx

Upload a custom avatar image for your project's Spectrum profile. The CLI handles getting a presigned URL, uploading the file, and updating the profile.

```sh
photon spectrum avatar upload photo.png
```

--------------------------------

### Manage Projects with Photon CLI

Source: https://github.com/photon-hq/docs/blob/main/cli/overview.mdx

List your projects and set the current project for your shell session by exporting the PHOTON_PROJECT_ID environment variable.

```sh
photon projects ls
```

```sh
export PHOTON_PROJECT_ID=<project-id>
```

--------------------------------

### Login to Photon CLI

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Initiates the device authorization flow for logging into the Photon CLI. This command opens your default browser for approval.

```bash
photon login
```

--------------------------------

### Check Billing Information

Source: https://github.com/photon-hq/docs/blob/main/cli/overview.mdx

Display current billing information using the Photon CLI.

```sh
photon billing show
```

--------------------------------

### Generate Stable Client GUIDs for Deduplication

Source: https://github.com/photon-hq/docs/blob/main/best-practices/recovery-and-state.mdx

Assign a deterministic `clientGuid` at enqueue time to ensure messages are unique across retries. This is crucial for preventing duplicate processing by the transport layer.

```typescript
const messages = reply.map((text, index) => ({
  text,
  clientGuid: `${jobId}-${index}`, // stable across retries
}));
```

--------------------------------

### Check for cancellation flag

Source: https://github.com/photon-hq/docs/blob/main/best-practices/inbound-pipeline.mdx

Compares the cancellation timestamp against the chain's start time to determine if an in-flight job should be aborted. This prevents stale flags from prior chains from affecting the current one.

```typescript
const inflight = await readInflight(chatId);
if (inflight?.cancelled_at && inflight.cancelled_at > chainStartedAt) {
  abortController.abort();
}
```

--------------------------------

### Create Photon Profile

Source: https://github.com/photon-hq/docs/blob/main/cli/profile-and-utilities.mdx

Initiates an interactive prompt to create a developer or organization profile. Flags can be passed for non-interactive use.

```sh
photon profile init
```

--------------------------------

### Authenticate API Requests with Basic Auth

Source: https://github.com/photon-hq/docs/blob/main/api-reference/introduction.mdx

Use your `projectId` as the username and `projectSecret` as the password for HTTP Basic authentication. Retrieve credentials via the `photon` CLI or dashboard. Rotate secrets if compromised.

```sh
curl -u "$PROJECT_ID:$PROJECT_SECRET" \
  "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/"
```

--------------------------------

### Verify Documentation Changes

Source: https://github.com/photon-hq/docs/blob/main/README.md

Run linting and type checking for documentation to ensure code quality and consistency before opening a pull request.

```bash
pnpm lint
pnpm typecheck:docs
```

--------------------------------

### Check Authentication Status for All Backends

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Displays the login status for all authenticated backends. Use `--json` for machine-readable output.

```bash
photon auth status
```

--------------------------------

### Expose local server with ngrok

Source: https://github.com/photon-hq/docs/blob/main/webhooks/quickstart.mdx

Use ngrok to expose your local development server to the internet, providing a public HTTPS URL for your webhook.

```bash
ngrok http 3000
```

--------------------------------

### Initialize Spectrum SDK for Outbound Messages

Source: https://github.com/photon-hq/docs/blob/main/webhooks/quickstart.mdx

This code initializes the Spectrum SDK in a long-lived process. It's designed to hold an outbound SDK instance that can be used to send messages in response to webhook events. Ensure you have your PROJECT_ID and PROJECT_SECRET environment variables set.

```typescript
import { Spectrum, text } from "spectrum-ts";
import { imessage } from "spectrum-ts/providers/imessage";

const app = await Spectrum({
  projectId: process.env.PROJECT_ID!,
  projectSecret: process.env.PROJECT_SECRET!,
  providers: [imessage.config()],
});

// call this from your webhook handler (e.g. via a queue / RPC)
export const reply = async (spaceId: string, body: string) => {
  const space = await app.spaces.get(spaceId);
  await space.send(text(body));
};
```

--------------------------------

### Set Backend Host via Environment Variable

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Sets the backend API host for all subsequent commands in the current shell session using the `PHOTON_API_HOST` environment variable.

```bash
export PHOTON_API_HOST=https://staging-app.photon.codes
photon projects ls
```

--------------------------------

### Authenticate CI with Token Environment Variable

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Authenticates a command using a provided token via the `PHOTON_TOKEN` environment variable, suitable for non-interactive environments.

```bash
PHOTON_TOKEN=ey... photon projects ls
```

--------------------------------

### Show Billing Information with JSON Output

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Retrieves billing information in JSON format. Requires the `--json` flag.

```bash
photon billing show --json
```

--------------------------------

### Set Backend Host via Command Flag

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Specifies the backend API host for a single command using the `--api-host` flag.

```bash
photon projects ls --api-host https://staging-app.photon.codes
```

--------------------------------

### Manage Spectrum Resources

Source: https://github.com/photon-hq/docs/blob/main/cli/overview.mdx

List Spectrum users and phone lines within your project using the CLI.

```sh
photon spectrum users ls
```

```sh
photon spectrum lines ls
```

--------------------------------

### Use TypeTooltip for Inline Type References

Source: https://github.com/photon-hq/docs/blob/main/CLAUDE.md

Use the TypeTooltip component to display type information inline. Pair it with a short prose description for readability without hover.

```mdx
{% set chatType = symbol("ts:@photon-ai/advanced-imessage#Chat") %}
Returns a <TypeTooltip name="Chat" type={`{{ chatType.signature }}`} /> with the chat's identifiers, participants, and status flags.
```

--------------------------------

### View Current Subscription Details

Source: https://github.com/photon-hq/docs/blob/main/cli/billing.mdx

Displays the active subscription for the current project, including plan details and status. Use the `--json` flag for programmatic access to the subscription data.

```sh
photon billing show
```

```sh
photon billing show --json
```

--------------------------------

### List Spectrum Platforms

Source: https://github.com/photon-hq/docs/blob/main/cli/spectrum.mdx

List all messaging platforms that are enabled or disabled for your project.

```sh
photon spectrum platforms ls
```

--------------------------------

### Log in to Staging Backend

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Logs into a specific staging backend using its API host. Credentials are stored per backend.

```bash
photon login --api-host https://staging-app.photon.codes
```

--------------------------------

### Update a Project

Source: https://github.com/photon-hq/docs/blob/main/cli/projects.mdx

Updates an existing project by providing its ID and the new name. The command fetches the current project details, applies your changes, and then patches the project. It defaults to the PHOTON_PROJECT_ID environment variable if no ID is specified.

```sh
photon projects update <project-id> --name "New Name"
```

--------------------------------

### Show Photon Auth Status

Source: https://github.com/photon-hq/docs/blob/main/cli/profile-and-utilities.mdx

Lists each backend with its credential status. Flags corrupt or invalid credential files.

```sh
photon auth status
```

```sh
photon auth status --json
```

--------------------------------

### Import TypeTooltip Component

Source: https://github.com/photon-hq/docs/blob/main/CLAUDE.md

Import the TypeTooltip component for inline type references. This is typically placed at the beginning of an MDX file.

```mdx
import { TypeTooltip } from "/snippets/type-tooltip.mdx";
```

--------------------------------

### List Spectrum Users

Source: https://github.com/photon-hq/docs/blob/main/cli/spectrum.mdx

List all users that can interact through your project's Spectrum instance. Supports JSON output.

```sh
photon spectrum users ls
```

```sh
photon spectrum users ls --json
```

--------------------------------

### Show Photon Profile

Source: https://github.com/photon-hq/docs/blob/main/cli/profile-and-utilities.mdx

Displays your account details and profile information.

```sh
photon profile show
```

--------------------------------

### List Registered Webhooks (Python)

Source: https://github.com/photon-hq/docs/blob/main/webhooks/managing-webhooks.mdx

Retrieve a list of all registered webhooks for your project using Python. The response includes webhook details but not the signing secret.

```py
import httpx, os

res = httpx.get(
    f"https://spectrum.photon.codes/projects/{os.environ['PROJECT_ID']}/webhooks/",
    auth=(os.environ['PROJECT_ID'], os.environ['PROJECT_SECRET']),
)

print(res.json()["data"])  # list of { id, webhookUrl, createdAt, updatedAt }
```

--------------------------------

### Register a Webhook (Python)

Source: https://github.com/photon-hq/docs/blob/main/webhooks/managing-webhooks.mdx

Registers a new webhook using Python's httpx library. The signing secret is returned only once and should be saved.

```py
import httpx, os

res = httpx.post(
    f"https://spectrum.photon.codes/projects/{os.environ['PROJECT_ID']}/webhooks/",
    auth=(os.environ['PROJECT_ID'], os.environ['PROJECT_SECRET']),
    json={"webhookUrl": "https://your-app.com/spectrum-webhook"},
)

data = res.json()["data"]
print("signingSecret:", data["signingSecret"])  # save this — only shown once
```

--------------------------------

### Show Spectrum Profile

Source: https://github.com/photon-hq/docs/blob/main/cli/spectrum.mdx

View the current Spectrum profile attached to your project.

```sh
# View the current profile
photon spectrum profile show
```

--------------------------------

### List Available Billing Plans

Source: https://github.com/photon-hq/docs/blob/main/cli/billing.mdx

Shows all available plans and their associated Stripe price IDs. These price IDs are necessary for subscribing to a plan.

```sh
photon billing plans
```

--------------------------------

### Create Collapsible Details with Accordion

Source: https://github.com/photon-hq/docs/blob/main/CLAUDE.md

Use the Accordion component to present reference material like option tables or enumerated values. The title should be the type name, and the description should use the symbol's summary.

```mdx
{% set opts = symbol("ts:@photon-ai/advanced-imessage#SendOptions") %}
<Accordion title="SendOptions" description="{{ opts.doc.summary }}">
  | Option | Type | Description |
  |---|---|---|
  {% for m in opts.members -%}
  | `{{ m.name }}` | `{{ m.type.text | replace("\n", " ") | replace("    ", "") | replace("|", "\\|") | replace("<", "&lt;") | replace(">", "&gt;") }}` | {{ m.doc.summary }} |
  {% endfor %}
</Accordion>
```

--------------------------------

### Set Backend Host Inline

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Sets the backend API host for a single command by prefixing the command with the environment variable assignment.

```bash
PHOTON_API_HOST=http://localhost:3000 photon projects ls
```

--------------------------------

### List Spectrum Lines

Source: https://github.com/photon-hq/docs/blob/main/cli/spectrum.mdx

List all phone lines assigned to your project.

```sh
photon spectrum lines ls
```

--------------------------------

### Open Stripe Customer Portal for Subscription Management

Source: https://github.com/photon-hq/docs/blob/main/cli/billing.mdx

Opens the Stripe Customer Portal in the browser, allowing users to update payment methods, change plans, view invoices, or cancel their subscription. Use `--no-browser` to print the portal URL to the terminal.

```sh
photon billing manage
```

--------------------------------

### Authenticate CI with Token Flag

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Authenticates a command using a provided token via the `--token` flag, suitable for non-interactive environments.

```bash
photon projects ls --token "$PHOTON_TOKEN"
```

--------------------------------

### Register a webhook

Source: https://github.com/photon-hq/docs/blob/main/webhooks/managing-webhooks.mdx

Registers a new webhook for the project. The signing secret is returned only once upon successful registration and should be saved securely.

```APIDOC
## POST /projects/{projectId}/webhooks/

### Description
Registers a new webhook URL for the project. The `signingSecret` is returned only in the response and must be saved securely as it will not be available again.

### Method
POST

### Endpoint
`https://spectrum.photon.codes/projects/{projectId}/webhooks/`

### Parameters
#### Request Body
- **webhookUrl** (string) - Required - The URL where webhook events will be sent.

### Request Example
```json
{
  "webhookUrl": "https://your-app.com/spectrum-webhook"
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the webhook.
- **webhookUrl** (string) - The registered webhook URL.
- **signingSecret** (string) - The secret key used for signing webhook payloads. This is only returned once.
- **createdAt** (string) - The timestamp when the webhook was created.
- **updatedAt** (string) - The timestamp when the webhook was last updated.

#### Response Example
```json
{
  "succeed": true,
  "data": {
    "id": "6a4d2e8c-7b1f-4d3a-9a8e-2c5d6f7e8a9b",
    "webhookUrl": "https://your-app.com/spectrum-webhook",
    "signingSecret": "a3f8e29b...5c7e9b2d",
    "createdAt": "2026-05-14T19:00:00Z",
    "updatedAt": "2026-05-14T19:00:00Z"
  }
}
```

### Errors
- **422**: `webhookUrl` fails schema validation (empty, malformed, etc.).
- **409**: The same URL is already registered for this project.
- **401**: Bad project credentials.
```

--------------------------------

### List Registered Webhooks (JavaScript)

Source: https://github.com/photon-hq/docs/blob/main/webhooks/managing-webhooks.mdx

Retrieve a list of all registered webhooks for your project using JavaScript. The response includes webhook details but not the signing secret.

```ts
const auth = Buffer.from(`${PROJECT_ID}:${PROJECT_SECRET}`).toString('base64');

const res = await fetch(
  `https://spectrum.photon.codes/projects/${PROJECT_ID}/webhooks/`,
  { headers: { Authorization: `Basic ${auth}` } }
);

const { data } = await res.json();
console.log(data); // array of { id, webhookUrl, createdAt, updatedAt }
```

--------------------------------

### Register a Webhook (JavaScript)

Source: https://github.com/photon-hq/docs/blob/main/webhooks/managing-webhooks.mdx

Registers a new webhook using JavaScript's fetch API. The signing secret is returned only once and should be saved.

```ts
const auth = Buffer.from(`${PROJECT_ID}:${PROJECT_SECRET}`).toString('base64');

const res = await fetch(
  `https://spectrum.photon.codes/projects/${PROJECT_ID}/webhooks/`,
  {
    method: 'POST',
    headers: {
      Authorization: `Basic ${auth}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ webhookUrl: 'https://your-app.com/spectrum-webhook' }),
  }
);

const { data } = await res.json();
console.log('signingSecret:', data.signingSecret); // save this — only shown once
```

--------------------------------

### Log Out from Photon CLI

Source: https://github.com/photon-hq/docs/blob/main/cli/authentication.mdx

Revokes your current session on the server and removes the local credential file.

```bash
photon logout
```

--------------------------------

### Register webhook URL with Spectrum

Source: https://github.com/photon-hq/docs/blob/main/webhooks/quickstart.mdx

Use curl to send a POST request to Spectrum to register your webhook URL. This requires your project ID and secret.

```bash
curl -X POST "https://spectrum.photon.codes/projects/$PROJECT_ID/webhooks/" \
    -u "$PROJECT_ID:$PROJECT_SECRET" \
    -H "Content-Type: application/json" \
    -d '{"webhookUrl":"https://abcd1234.ngrok-free.app/spectrum-webhook"}'
```

--------------------------------

### Mermaid Flowchart for Inbound Pipeline

Source: https://github.com/photon-hq/docs/blob/main/best-practices/architecture.mdx

Visualizes the stages of the inbound message pipeline, including batching, debouncing, generation, and sending. This diagram illustrates the flow of messages through a job queue system.

```mermaid
flowchart LR
  In([Incoming message]) --> BQ[(Batch queue)]
  BQ -->|debounce window| Flush[Batch flush]
  Flush --> Read[Mark as read]
  Read --> Gen[Generate reply]
  Gen --> Send[Send with pacing]
  Send --> Done([Done])

  Inflight[(In-flight table)] -.tracks.- Flush
  Inflight -.tracks.- Read
  Inflight -.tracks.- Gen
  Inflight -.tracks.- Send
```