diff --git a/.gitignore b/.gitignore
index 2fd2fd4..360a6a5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
node_modules
.typecheck-output
+.DS_Store
.pnpm-store
diff --git a/cli/authentication.mdx b/cli/authentication.mdx
index 95a31f3..13d87f9 100644
--- a/cli/authentication.mdx
+++ b/cli/authentication.mdx
@@ -13,6 +13,14 @@ photon login
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:
```sh
@@ -25,7 +33,12 @@ photon login --no-browser
photon whoami
```
-Prints your user ID, email, and name. If the session has expired, you'll see a hint to re-run `photon login`.
+Prints your name, email, and the backend you're signed in to. If the session has expired, you'll see a hint to re-run `photon login`.
+
+
+
+
+
## Log out
diff --git a/cli/billing.mdx b/cli/billing.mdx
index 14a38e8..78ac34b 100644
--- a/cli/billing.mdx
+++ b/cli/billing.mdx
@@ -24,6 +24,14 @@ photon billing show --json
Displays the active subscription for the current project, including plan details and status.
+
+
+
+
+
+
+
+
## Start a checkout
```sh
@@ -40,6 +48,10 @@ photon billing checkout --plan price_xxx
When you run this command, the CLI creates a Stripe Checkout session and opens it in your browser. If you don't pass any arguments, you get an interactive picker listing the available plans. Pass a `[tier]` positional or `--plan ` to skip the picker.
+
+
+
+
Available tiers: `pro`, `business`, `enterprise`.
| Flag | Description |
diff --git a/cli/installation.mdx b/cli/installation.mdx
index 0d8f1ce..a3f1b2d 100644
--- a/cli/installation.mdx
+++ b/cli/installation.mdx
@@ -3,17 +3,6 @@ title: Installation
description: Install the Photon CLI via npm, or as a standalone binary
---
-{/* ## Homebrew (macOS / Linux)
-
-If you're on macOS or Linux, Homebrew is the easiest option. You get a self-contained binary with no runtime dependencies.
-
-```sh
-brew install photon-hq/photon/photon
-photon login
-```
-
-Updates automatically with `brew upgrade photon`. */}
-
## One-off — no install
You can run any CLI command on demand without a global install:
diff --git a/cli/overview.mdx b/cli/overview.mdx
index 80bc892..99c8477 100644
--- a/cli/overview.mdx
+++ b/cli/overview.mdx
@@ -33,6 +33,10 @@ photon spectrum lines ls
photon billing show
```
+
+
+
+
## Command tree
```text
diff --git a/cli/profile-and-utilities.mdx b/cli/profile-and-utilities.mdx
index 29ef3ff..34a21de 100644
--- a/cli/profile-and-utilities.mdx
+++ b/cli/profile-and-utilities.mdx
@@ -26,10 +26,14 @@ Walks you through an interactive prompt to create a developer or organization pr
### Update your profile
```sh
-photon profile update --display-name "Jane Doe"
+# Developer profile
+photon profile update --languages typescript,python
+
+# Organization profile
+photon profile update --company-name "Acme Inc" --role "Engineering"
```
-Updates specific fields on your existing profile. The available flags differ based on whether you have a developer or organization profile.
+Updates specific fields on your existing profile. The available flags differ based on whether you have a developer or organization profile — run `photon profile update --help` for the full list.
Aliases: `profile edit`.
@@ -73,7 +77,7 @@ Show the authenticated user for the current backend:
photon whoami
```
-Prints your user ID, email, and name. Returns an error with a login hint if your session has expired.
+Prints your name, email, and the backend you're signed in to. Returns an error with a login hint if your session has expired.
### auth status
diff --git a/cli/projects.mdx b/cli/projects.mdx
index 1d28f52..ae2a962 100644
--- a/cli/projects.mdx
+++ b/cli/projects.mdx
@@ -14,6 +14,10 @@ photon projects ls --json
Aliases: `project ls`, `projects list`.
+
+
+
+
## Show project details
```sh
@@ -23,23 +27,33 @@ photon projects show
Defaults to `$PHOTON_PROJECT_ID` if no ID is given. Aliases: `projects get`.
+
+
+
+
## Create a project
```sh
photon projects create
```
+
+
+
+
Without flags, the CLI walks you through an interactive prompt. You can also pass flags directly:
```sh
-photon projects create --name "My Project" --location us-east --spectrum
+photon projects create --name "My Project" --location "United States" --spectrum
```
| Flag | Description |
|------|-------------|
-| `--name ` | Project name |
-| `--location ` | Deployment region |
-| `--spectrum` | Enable Spectrum for the project |
+| `-n, --name ` | Project name |
+| `-l, --location ` | Location (default: `United States`) |
+| `--spectrum` / `--no-spectrum` | Enable / disable Spectrum |
+| `--template` | Use the project as a template |
+| `--observability` | Enable observability |
Aliases: `projects new`.
@@ -75,6 +89,10 @@ 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
@@ -112,6 +130,10 @@ photon projects upgrade --plan price_xxx
Available tiers: `pro`, `business`, `enterprise`.
+
+
+
+
| Flag | Description |
|------|-------------|
| `[tier]` | Positional tier (`pro` / `business` / `enterprise`). Skips the picker. |
diff --git a/cli/spectrum.mdx b/cli/spectrum.mdx
index f036903..9bca4c9 100644
--- a/cli/spectrum.mdx
+++ b/cli/spectrum.mdx
@@ -16,7 +16,7 @@ View or update the Spectrum profile attached to your project.
photon spectrum profile show
# Update profile fields
-photon spectrum profile update --display-name "Support Bot"
+photon spectrum profile update --first-name "Support" --last-name "Bot"
```
Aliases: `spectrum profile edit`.
@@ -66,6 +66,10 @@ photon spectrum lines ls
Aliases: `spectrum lines list`.
+
+
+
+
### Add a line
```sh
diff --git a/images/cli/authentication/login-cli.avif b/images/cli/authentication/login-cli.avif
new file mode 100644
index 0000000..ff2f308
Binary files /dev/null and b/images/cli/authentication/login-cli.avif differ
diff --git a/images/cli/authentication/login-web.avif b/images/cli/authentication/login-web.avif
new file mode 100644
index 0000000..dbb37e3
Binary files /dev/null and b/images/cli/authentication/login-web.avif differ
diff --git a/images/cli/authentication/whoami-cli.avif b/images/cli/authentication/whoami-cli.avif
new file mode 100644
index 0000000..d351b42
Binary files /dev/null and b/images/cli/authentication/whoami-cli.avif differ
diff --git a/images/cli/billing/demo-billing.webm b/images/cli/billing/demo-billing.webm
new file mode 100644
index 0000000..f92466b
Binary files /dev/null and b/images/cli/billing/demo-billing.webm differ
diff --git a/images/cli/billing/demo-regenerate-secret.webm b/images/cli/billing/demo-regenerate-secret.webm
new file mode 100644
index 0000000..4823da0
Binary files /dev/null and b/images/cli/billing/demo-regenerate-secret.webm differ
diff --git a/images/cli/billing/demo-upgrade.webm b/images/cli/billing/demo-upgrade.webm
new file mode 100644
index 0000000..bc36ebc
Binary files /dev/null and b/images/cli/billing/demo-upgrade.webm differ
diff --git a/images/cli/billing/free.avif b/images/cli/billing/free.avif
new file mode 100644
index 0000000..06df79b
Binary files /dev/null and b/images/cli/billing/free.avif differ
diff --git a/images/cli/billing/paid.avif b/images/cli/billing/paid.avif
new file mode 100644
index 0000000..80e532d
Binary files /dev/null and b/images/cli/billing/paid.avif differ
diff --git a/images/cli/overview/demo-overview.webm b/images/cli/overview/demo-overview.webm
new file mode 100644
index 0000000..342ec63
Binary files /dev/null and b/images/cli/overview/demo-overview.webm differ
diff --git a/images/cli/projects/demo-create.webm b/images/cli/projects/demo-create.webm
new file mode 100644
index 0000000..6bdef40
Binary files /dev/null and b/images/cli/projects/demo-create.webm differ
diff --git a/images/cli/projects/projects-ls.avif b/images/cli/projects/projects-ls.avif
new file mode 100644
index 0000000..b54df35
Binary files /dev/null and b/images/cli/projects/projects-ls.avif differ
diff --git a/images/cli/projects/projects-show.avif b/images/cli/projects/projects-show.avif
new file mode 100644
index 0000000..ed7d2a8
Binary files /dev/null and b/images/cli/projects/projects-show.avif differ
diff --git a/images/cli/spectrum/spectrum-lines.avif b/images/cli/spectrum/spectrum-lines.avif
new file mode 100644
index 0000000..4096ee8
Binary files /dev/null and b/images/cli/spectrum/spectrum-lines.avif differ