Skip to content

Commit 2e85ddb

Browse files
lcandy2cursoragent
lcandy2
and
cursoragent
authored
docs: add CLI documentation (#22)
* docs: add CLI documentation tab with 7 pages Adds a new "CLI" tab to the docs site covering the Photon CLI (@photon-ai/cli). Includes Getting Started (overview, installation, authentication) and Commands (projects, spectrum, billing, profile & utilities) sections. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(docs): address review feedback on CLI documentation - Make standalone binary example platform-aware with <os>-<arch> placeholders - Use consistent second-person voice ("you") throughout installation page - Add prerequisite note before Quick Demo in overview - Clarify npx section requires Bun runtime - Add --json and --no-browser to billing common flags table Addresses Copilot/CodeRabbit feedback on #22. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 743f856 commit 2e85ddb

8 files changed

Lines changed: 746 additions & 0 deletions

File tree

‎cli/authentication.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: Authentication
3+
description: Log in, manage tokens, work with multiple backends, and authenticate in CI
4+
---
5+
6+
## Device flow login
7+
8+
The CLI uses a device authorization flow — you approve the login from a browser, no password is typed into the terminal.
9+
10+
```sh
11+
photon login
12+
```
13+
14+
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.
15+
16+
If you're on a headless machine (SSH session, container), pass `--no-browser` to get a URL you can open elsewhere:
17+
18+
```sh
19+
photon login --no-browser
20+
```
21+
22+
## Verify your session
23+
24+
```sh
25+
photon whoami
26+
```
27+
28+
Prints your user ID, email, and name. If the session has expired, you'll see a hint to re-run `photon login`.
29+
30+
## Log out
31+
32+
```sh
33+
photon logout
34+
```
35+
36+
Revokes the session on the server and deletes the local credential file.
37+
38+
## Credential storage
39+
40+
Credentials are stored as JSON files with `600` permissions:
41+
42+
```
43+
$PHOTON_CONFIG_DIR/credentials/<backend-key>.json
44+
```
45+
46+
The config directory is resolved in this order:
47+
48+
1. `$PHOTON_CONFIG_DIR` — explicit override
49+
2. `$XDG_CONFIG_HOME/photon` — XDG standard
50+
3. `~/.config/photon/` — default
51+
52+
<Note>
53+
If a legacy `~/.config/photon-dashboard/` directory exists from a prior install, it migrates automatically on first run.
54+
</Note>
55+
56+
### Multi-backend credentials
57+
58+
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`).
59+
60+
```sh
61+
# Log in to production (default)
62+
photon login
63+
64+
# Log in to staging
65+
photon login --api-host https://staging-app.photon.codes
66+
67+
# Check all backends at once
68+
photon auth status
69+
```
70+
71+
`photon auth status` shows the login state for every backend you've authenticated against. Pass `--json` for machine-readable output.
72+
73+
## Backend host
74+
75+
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:
76+
77+
```sh
78+
# Environment variable — applies to every command in this shell
79+
export PHOTON_API_HOST=https://staging-app.photon.codes
80+
photon projects ls
81+
82+
# Per-command flag
83+
photon projects ls --api-host https://staging-app.photon.codes
84+
85+
# Inline
86+
PHOTON_API_HOST=http://localhost:3000 photon projects ls
87+
```
88+
89+
Resolution order: `--api-host` flag > `PHOTON_API_HOST` env var > built-in production URL.
90+
91+
Check the resolved host with:
92+
93+
```sh
94+
photon env current
95+
```
96+
97+
## Setting an active project
98+
99+
Most commands operate on a single project. Specify it per-command or per-shell:
100+
101+
```sh
102+
# Per command
103+
photon spectrum users ls --project abc123
104+
105+
# Per shell session
106+
export PHOTON_PROJECT_ID=abc123
107+
photon spectrum users ls
108+
```
109+
110+
Resolution order: `--project` flag > `$PHOTON_PROJECT_ID` > error with a hint.
111+
112+
<Note>
113+
Put `export PHOTON_PROJECT_ID='...'` in your shell rc, or use [direnv](https://direnv.net/) to scope it to a project directory.
114+
</Note>
115+
116+
## CI and scripting
117+
118+
For non-interactive environments, pass a token directly instead of running the device flow:
119+
120+
```sh
121+
# Flag
122+
photon projects ls --token "$PHOTON_TOKEN"
123+
124+
# Environment variable
125+
PHOTON_TOKEN=ey... photon projects ls
126+
```
127+
128+
Get the token from your local credentials file (under `$PHOTON_CONFIG_DIR/credentials/<key>.json`) after authenticating once with `photon login`.
129+
130+
Pair with `--json` for machine-readable output:
131+
132+
```sh
133+
photon projects ls --json | jq '.[] | .id'
134+
photon billing show --json
135+
```
136+
137+
| Flag / env var | Effect |
138+
|----------------|--------|
139+
| `-t, --token <token>` / `PHOTON_TOKEN` | Use this token instead of stored credentials |
140+
| `--json` | Structured JSON output |
141+
| `--yes`, `-y` | Skip destructive-action confirmation prompts |
142+
| `--no-browser` | Don't auto-open the browser |
143+
144+
<Note>
145+
`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.
146+
</Note>

‎cli/billing.mdx‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: Billing
3+
description: View plans, manage subscriptions, and open Stripe portals from the CLI
4+
---
5+
6+
The `photon billing` commands let you view available plans, check your current subscription, start a checkout, and manage billing through the Stripe Customer Portal.
7+
8+
All billing commands require an active project. Set `$PHOTON_PROJECT_ID` or pass `--project <id>`.
9+
10+
## List available plans
11+
12+
```sh
13+
photon billing plans
14+
```
15+
16+
Shows all plans and their Stripe price IDs. Use the price ID with `checkout` to subscribe.
17+
18+
## View current subscription
19+
20+
```sh
21+
photon billing show
22+
photon billing show --json
23+
```
24+
25+
Displays the active subscription for the current project, including plan details and status.
26+
27+
## Start a checkout
28+
29+
```sh
30+
photon billing checkout --plan <price-id>
31+
photon billing checkout --plan <price-id> --qty 5
32+
```
33+
34+
Creates a Stripe Checkout session and opens it in your browser. Pass `--no-browser` to print the URL instead, or `--json` to get the session URL programmatically.
35+
36+
| Flag | Description |
37+
|------|-------------|
38+
| `--plan <price-id>` | Stripe price ID (required — get it from `billing plans`) |
39+
| `--qty <number>` | Quantity for the line item |
40+
| `--no-browser` | Print the checkout URL instead of opening it |
41+
| `--json` | Output the checkout session as JSON |
42+
43+
## Manage subscription (Stripe Portal)
44+
45+
```sh
46+
photon billing manage
47+
```
48+
49+
Opens the Stripe Customer Portal where you can update payment methods, change plans, view invoices, or cancel. Pass `--no-browser` to get the portal URL printed to the terminal.
50+
51+
Aliases: `billing portal`.
52+
53+
## Common flags
54+
55+
| Flag | Env var | Description |
56+
|------|---------|-------------|
57+
| `-p, --project <id>` | `PHOTON_PROJECT_ID` | Target project |
58+
| `--api-host <url>` | `PHOTON_API_HOST` | Override the backend URL |
59+
| `-t, --token <token>` | `PHOTON_TOKEN` | Use this token instead of stored credentials |
60+
| `--json` | — | Output as JSON |
61+
| `--no-browser` | — | Print URL instead of opening the browser |

‎cli/installation.mdx‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: Installation
3+
description: Install the Photon CLI via Homebrew, npm, Bun, or as a standalone binary
4+
---
5+
6+
## Homebrew (macOS / Linux)
7+
8+
If you're on macOS or Linux, Homebrew is the easiest option. You get a self-contained binary with no runtime dependencies.
9+
10+
```sh
11+
brew install photon-hq/photon/photon
12+
photon login
13+
```
14+
15+
Updates automatically with `brew upgrade photon`.
16+
17+
## One-off with npx / bunx
18+
19+
You can run any CLI command on demand without a global install:
20+
21+
<CodeGroup>
22+
```sh npx
23+
npx @photon-ai/cli login
24+
npx @photon-ai/cli projects ls
25+
```
26+
27+
```sh bunx
28+
bunx @photon-ai/cli login
29+
bunx @photon-ai/cli projects ls
30+
```
31+
</CodeGroup>
32+
33+
Each time you run it, it pulls the latest release automatically. This is useful for scripts, throwaway machines, or trying the CLI before committing.
34+
35+
<Note>
36+
The npm bundle uses a `#!/usr/bin/env bun` shebang, so you need Bun on your `PATH`. Install it with:
37+
38+
```sh
39+
curl -fsSL https://bun.sh/install | bash
40+
```
41+
</Note>
42+
43+
## Global install with Bun
44+
45+
For daily use, you can install globally so `photon` is always on your `PATH`:
46+
47+
```sh
48+
bun add -g @photon-ai/cli
49+
photon login
50+
```
51+
52+
The `pho` shortcut alias is created automatically the first time you run `photon`.
53+
54+
## Standalone binary
55+
56+
If you don't want any runtime dependency (e.g. CI environments), you can download a prebuilt binary directly. Replace `<os>` and `<arch>` with your platform:
57+
58+
```sh
59+
# <os>: darwin | linux
60+
# <arch>: arm64 | x64
61+
curl -L -o /usr/local/bin/photon \
62+
https://github.com/photon-hq/cli/releases/latest/download/photon-<os>-<arch>
63+
chmod +x /usr/local/bin/photon
64+
photon --version
65+
```
66+
67+
For example, on an Apple Silicon Mac:
68+
69+
```sh
70+
curl -L -o /usr/local/bin/photon \
71+
https://github.com/photon-hq/cli/releases/latest/download/photon-darwin-arm64
72+
chmod +x /usr/local/bin/photon
73+
```
74+
75+
Available platforms:
76+
77+
| Platform | Architectures |
78+
|----------|--------------|
79+
| macOS | arm64, x64 |
80+
| Linux | arm64, x64 |
81+
82+
Each binary ships with a corresponding `.sha256` checksum on the [release page](https://github.com/photon-hq/cli/releases/latest).
83+
84+
## Verify the installation
85+
86+
```sh
87+
photon --version
88+
photon ping
89+
```
90+
91+
`photon ping` hits the Photon API health endpoint — if you see a success response, you're ready to [authenticate](/cli/authentication).

‎cli/overview.mdx‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Photon CLI
3+
description: Manage projects, Spectrum, billing, and your profile from the terminal
4+
---
5+
6+
The Photon CLI replaces the [Dashboard](https://app.photon.codes) web UI for everyday work. Manage projects, Spectrum users and lines, billing, and your developer profile — all from a terminal.
7+
8+
```sh
9+
npx @photon-ai/cli login
10+
```
11+
12+
## Quick demo
13+
14+
After [installing](/cli/installation) the CLI:
15+
16+
```sh
17+
# Log in (opens a browser to approve the device)
18+
photon login
19+
20+
# List your projects
21+
photon projects ls
22+
23+
# Set a project for the current shell session
24+
export PHOTON_PROJECT_ID=<project-id>
25+
26+
# Manage Spectrum resources
27+
photon spectrum users ls
28+
photon spectrum lines ls
29+
30+
# Check billing
31+
photon billing show
32+
```
33+
34+
## Command tree
35+
36+
```text
37+
photon
38+
├── ping hit /api/health
39+
├── env current print resolved API host
40+
├── login [--api-host] [--no-browser] device-auth login
41+
├── logout [--api-host] clear stored credentials
42+
├── whoami [--api-host] current user on this backend
43+
├── auth status [--json] login state across all backends
44+
├── config show [--json] dump active configuration
45+
├── profile
46+
│ ├── show account & profile details
47+
│ ├── init create developer or org profile
48+
│ └── update [flags] update profile fields
49+
├── projects
50+
│ ├── ls [--json] list projects
51+
│ ├── show [id] [--json] project detail
52+
│ ├── create [--name --location --spectrum] new project
53+
│ ├── update [id] [flags] rename / toggle flags
54+
│ ├── delete [id] [-y] permanent delete
55+
│ ├── regenerate-secret [id] [-y] rotate Spectrum API secret
56+
│ ├── open [id] [--no-browser] open dashboard in browser
57+
│ └── check-phone <number> phone number availability
58+
├── spectrum
59+
│ ├── profile show / update project Spectrum profile
60+
│ ├── users ls / add / remove manage Spectrum users
61+
│ ├── lines ls / add / remove manage phone lines
62+
│ ├── platforms ls / enable / disable toggle messaging platforms
63+
│ └── avatar upload <file> upload Spectrum avatar
64+
└── billing
65+
├── plans available plans
66+
├── show [--json] current subscription
67+
├── checkout --plan <price-id> [--qty] Stripe Checkout
68+
└── manage Stripe Customer Portal
69+
```
70+
71+
Run `photon <command> --help` for the full flag list of any command.
72+
73+
## The `pho` alias
74+
75+
After installing globally, a `pho` shortcut is created automatically the first time you run `photon`:
76+
77+
```sh
78+
pho projects ls # same as: photon projects ls
79+
pho whoami
80+
```
81+
82+
The alias is only available for global installs — `npx` / `bunx` users don't get it since they're already typing the full package name.
83+
84+
## Global flags
85+
86+
| Flag | Env var | Effect |
87+
|------|---------|--------|
88+
| `--debug` | `PHOTON_DEBUG=1` | Verbose HTTP request/response logs to stderr |
89+
| `--version`, `-v` | — | Print CLI version |
90+
| `--no-color` | `NO_COLOR=1` | Disable colored output ([NO_COLOR standard](https://no-color.org/)) |
91+
92+
All other flags (`--api-host`, `--project`, `--token`, `--json`, `--yes`, `--no-browser`) are **per-command** and must appear after the subcommand name.

0 commit comments

Comments
 (0)