> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.
# Projects
> Select an active project and manage its resources and settings.
A project is the unit that owns your Photon resources — phone numbers, email
domains, API keys, webhooks, and billing. Every project belongs to an
[organization](/docs/beta/cli/organizations), which also holds its members.
`photon project` manages projects and everything inside them.
```sh theme={null}
photon project list
photon project create --name "Support line" --slug support-line --use
photon project current
```
## Command overview
[Browse the automatic command reference](/docs/beta/cli/reference/index).
Every node generates its own help and shell completion. Run any of them with
`--help`, such as `photon project create --help`.
Phone numbers, email domains, and voice routing.
Query project logs, traces, and restricted SQL.
Issue and revoke project API keys.
Subscribe endpoints to project events.
The name and avatar your project presents.
Plans, subscriptions, and invoices.
Register numbers for call compliance.
## Projects in an organization
`project list`, `project count`, and `project create` work in the
[selected organization](/docs/beta/cli/organizations#select-an-organization): your stored
organization, your only organization, or `--org` for one invocation.
```sh theme={null}
photon project list
photon project create --name "Support line" --slug support-line --org org_123
```
Project resources include `organizationId`. The project membership `role` is
gone, and so is the `--role` filter: access comes from your organization role.
`photon project member`, `project invitation`, and `project leave` moved to
[`photon org`](/docs/beta/cli/organizations#moved-commands). The old names only print
the replacement and exit with code `2`.
## Select an active project
Most commands are project-scoped. They resolve the project in this order:
1. The global `--project ` flag, for that invocation only.
2. A non-empty `PHOTON_PROJECT_ID` environment variable.
3. Your stored active project.
```sh theme={null}
photon project use project_123 # store an active project
photon project current # show it and where it came from
photon --project project_456 project view
PHOTON_PROJECT_ID=project_789 photon project view
photon project clear # forget the stored selection
```
`photon project current` reports the source as `flag`, `environment`, or
`stored`. An empty `PHOTON_PROJECT_ID` is ignored rather than treated as a
selection.
`project use` fetches the project before storing it, so you can never make an
inaccessible ID active. `project create --use` activates the project it just
created. Deleting your stored active project clears the selection,
and `project clear` warns you if `PHOTON_PROJECT_ID` still takes precedence.
Your selection is tied to the authenticated identity and API origin, and is
stored in Photon's configuration directory rather than in the working
directory — so it follows you between repositories rather than between machines.
## Pagination and filters
Paginated list commands default to `--limit 30`. The CLI follows page tokens
for you until it has that many records or reaches the last page, preserving the
order the API returned.
When more records remain, JSON output includes `nextPageToken`. Pass it back
with `--page-token` to continue:
```sh theme={null}
photon project list \
--search support \
--created-after 2026-07-01T00:00:00Z \
--limit 100 \
--json
```
Timestamps accept RFC 3339 input and are normalized to UTC; `--created-after`
cannot be later than `--created-before`.
`api-key list` is not paginated — the SDK returns every live key, newest
first.
## JSON contracts
Global `--json` prints one object on stdout and sends warnings and errors to
stderr. Collections use a named envelope:
```json theme={null}
{"projects":[],"nextPageToken":"opaque-token"}
{"assignments":[]}
{"resources":[],"provisioning":[],"nextPageToken":"opaque-resource-token"}
{"invoices":[]}
{"apiKeys":[]}
{"registrations":[],"nextPageToken":"opaque-token"}
{"destinations":[],"nextPageToken":"opaque-token"}
{"apiVersions":[]}
```
Single resources use the singular form — `project`, `agentProfile`, `assignment`, `operation`, `subscription`, `billing`,
`platform`, `resource`, `profile`, `registration`, and `destination`.
`platform list` returns its catalog as `{"platforms": [...]}`.
Context results add a `source` field. Destructive results add an explicit
`deleted`, `disconnected`, `removed`, `released`, or `revoked` boolean.
Declining a confirmation prints this and exits `0`:
```json theme={null}
{"cancelled":true}
```
Only documented SDK fields are selected into JSON, so a new upstream response
field does not silently become part of the CLI's contract.
See [JSON output and exit codes](/docs/beta/cli/output) for the error envelope and
`--debug` traces.
## Confirmations
Destructive commands ask before they act. Interactive input accepts `y` or
`yes`; anything else cancels. When stdin is not a terminal, pass `--force` —
without it the command exits `2` and changes nothing.
```sh theme={null}
photon project delete
photon project delete --force --json
```
* Project deletion
* API key revocation
* Agent avatar reset
* iMessage assignment release
* Subscription cancellation
* Plan purchase
* Email-domain disconnection
* SMS-number purchase
* SMS-number deletion
* Voice profile inbound changes that affect assigned lines
* Voice profile outbound credential rotation and revocation
* Voice profile assignment changes
* Voice profile deletion
* Call Registry profile replacement
* Call Registry automatic-registration changes
* Call Registry registration submission
* Webhook destination deletion
* Webhook signing-secret rotation
## Recovery
Most state-changing calls are protected by a local write-ahead journal, so a
mutation whose result you never saw can be replayed rather than guessed at. See
[Recoverable operations](/docs/beta/cli/operations).
Call Registry profile changes are the exception: their request bodies contain
private profile data, so they are not journaled. Their idempotency key is
included in uncertain errors instead, which lets automation repeat the exact
input under the same key.
Project creation requires a unique `--slug`: 3–63 lowercase letters or digits, with single hyphens between words.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.