Skip to main content
Projects are the top-level container in Photon. Each project has its own Spectrum configuration, users, lines, and billing subscription.

​
List projects

photon projects ls
photon projects ls --json
Aliases: project ls, projects list.

​
Show project details

photon projects show
photon projects show <project-id>
Defaults to $PHOTON_PROJECT_ID if no ID is given. Aliases: projects get.

​
Create a project

photon projects create
Without flags, the CLI walks you through an interactive prompt. You can also pass flags directly: 
photon projects create --name "My Project" --location us-east --spectrum
FlagDescription
--name <name>Project name
--location <loc>Deployment region
--spectrumEnable Spectrum for the project
Aliases: projects new.

​
Update a project

photon projects update <project-id> --name "New Name"
Fetches the current project, overlays your changes, and patches. Defaults to $PHOTON_PROJECT_ID if no ID is given. Aliases: projects edit, projects set.

​
Delete a project

photon projects delete <project-id>
photon projects delete <project-id> -y   # skip confirmation
This is a permanent, irreversible operation. The CLI asks for confirmation unless you pass -y.
Aliases: projects rm, projects remove.

​
Rotate the Spectrum API secret

photon projects regenerate-secret <project-id>
photon projects regenerate-secret -y
Generates a new Spectrum API secret for the project. The old secret stops working immediately. Aliases: projects rotate-secret.

​
Open in the dashboard

photon projects open
photon projects open <project-id>
photon projects open --no-browser   # prints the URL instead
Opens the project’s Dashboard page in your default browser.

​
Upgrade subscription

Use this command to subscribe a project or manage its existing subscription. The CLI routes you to the right Stripe surface based on the project’s current state:
  • Free or unsubscribed projects — opens Stripe Checkout
  • Active or past-due subscriptions — opens the Stripe Customer Portal (change plan, payment method, cancel, etc.)
# Interactive picker (recommended)
photon projects upgrade

# Skip the picker with a positional tier
photon projects upgrade pro
photon projects upgrade <project-id> business

# Force a specific flow
photon projects upgrade --checkout         # always Checkout, even if subscribed
photon projects upgrade --manage           # always Portal (downgrade / cancel / change card)

# Use a specific Stripe price (escape hatch)
photon projects upgrade --plan price_xxx
Available tiers: pro, business, enterprise.
FlagDescription
[tier]Positional tier (pro / business / enterprise). Skips the picker.
--plan <price-id>Stripe price ID. Escape hatch when you need a specific price.
--qty <n>Quantity (default 1)
--checkoutForce Checkout even if the project already has a subscription
--manageForce the Stripe Customer Portal (use this for downgrades / cancellation)
--no-browserPrint the URL instead of opening it
--jsonOutput {action, url, tier?} as JSON and skip opening the browser
--manage wins over [tier] / --plan / --checkout when both are passed. Downgrades and cancellations live in the Stripe Portal — there’s no dedicated downgrade command.

​
Check phone number availability

photon projects check-phone +15551234567
Checks whether a phone number is available for Spectrum.

​
Common flags

These flags are available on most project commands:
FlagEnv varDescription
-p, --project <id>PHOTON_PROJECT_IDTarget project (defaults to env var)
--api-host <url>PHOTON_API_HOSTOverride the backend URL
-t, --token <token>PHOTON_TOKENUse this token instead of stored credentials
--json—Output as JSON
-y, --yes—Skip confirmation prompts