Skip to main content
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, which also holds its members. photon project manages projects and everything inside them.

​
Command overview

Browse the automatic command reference. Every node generates its own help and shell completion. Run any of them with --help, such as photon project create --help.

Platform resources

Phone numbers, email domains, and voice routing.

Developer telemetry

Query project logs, traces, and restricted SQL.

API keys

Issue and revoke project API keys.

Webhooks

Subscribe endpoints to project events.

Agent profile

The name and avatar your project presents.

Billing

Plans, subscriptions, and invoices.

Call Registry

Register numbers for call compliance.

​
Projects in an organization

project list, project count, and project create work in the selected organization: your stored organization, your only organization, or --org for one invocation.
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. 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 <project-id> flag, for that invocation only.
  2. A non-empty PHOTON_PROJECT_ID environment variable.
  3. Your stored active project.
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:
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:
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:
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 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.
  • 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. 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.