Skip to main content

​
Device flow login

The CLI uses a device authorization flow — you approve the login from a browser, no password is typed into the terminal.
This opens your default browser to the Photon approval page. Once you approve, the CLI stores your access token locally and you’re ready to go. If you’re on a headless machine (SSH session, container), pass --no-browser to get a URL you can open elsewhere:

​
Verify your session

Prints your user ID, email, and name. If the session has expired, you’ll see a hint to re-run photon login.

​
Log out

Revokes the session on the server and deletes the local credential file.

​
Credential storage

Credentials are stored as JSON files with 600 permissions:
The config directory is resolved in this order:
  1. $PHOTON_CONFIG_DIR — explicit override
  2. $XDG_CONFIG_HOME/photon — XDG standard
  3. ~/.config/photon/ — default
If a legacy ~/.config/photon-dashboard/ directory exists from a prior install, it migrates automatically on first run.

​
Multi-backend credentials

Credentials are stored per backend. You can be logged into production and a staging server simultaneously — each gets its own credential file keyed by a sanitized hostname (e.g. production, staging-app_photon_codes, localhost_3000).
photon auth status shows the login state for every backend you’ve authenticated against. Pass --json for machine-readable output.

​
Backend host

Every command talks to a backend URL. The default is production (https://app.photon.codes). To target a different backend, set PHOTON_API_HOST or use the --api-host flag:
Resolution order: --api-host flag > PHOTON_API_HOST env var > built-in production URL. Check the resolved host with:

​
Setting an active project

Most commands operate on a single project. Specify it per-command or per-shell:
Resolution order: --project flag > $PHOTON_PROJECT_ID > error with a hint.
Put export PHOTON_PROJECT_ID='...' in your shell rc, or use direnv to scope it to a project directory.

​
CI and scripting

For non-interactive environments, pass a token directly instead of running the device flow:
Get the token from your local credentials file (under $PHOTON_CONFIG_DIR/credentials/<key>.json) after authenticating once with photon login. Pair with --json for machine-readable output:
PHOTON_TOKEN reuses the access token from the device flow (default 7-day expiry). Re-run photon login when it expires. A long-lived API key path is on the roadmap.