Skip to content

docs: Update CLI docs to match spec #93

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Rice (invisicat) wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: Update CLI docs to match spec #93

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5107bfa
docs: fix CLI flag inconsistencies in cli pages
invisicat Jun 20, 2026
6a1fbb1
docs: remove Homebrew install section
invisicat Jun 20, 2026
6568be6
docs: add screenshots and demo videos to CLI pages
invisicat Jun 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
node_modules
.typecheck-output
.DS_Store

.pnpm-store

Expand Down
15 changes: 14 additions & 1 deletion cli/authentication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Frame caption="Running photon login in the terminal.">
<img src="/images/cli/authentication/login-cli.avif" alt="Terminal running photon login, showing the device code and approval URL" style={{ padding: "1rem" }} />
</Frame>

<Frame caption="Approving the device login in the browser.">
<img src="/images/cli/authentication/login-web.avif" alt="Photon browser approval page for the device login flow" style={{ padding: "1rem" }} />
</Frame>

If you're on a headless machine (SSH session, container), pass `--no-browser` to get a URL you can open elsewhere:

```sh
Expand All @@ -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`.

<Frame caption="Terminal output of photon whoami showing name, email, and backend.">
<img src="/images/cli/authentication/whoami-cli.avif" alt="Terminal output of photon whoami showing name, email, and backend" />
</Frame>


## Log out

Expand Down
12 changes: 12 additions & 0 deletions cli/billing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,14 @@ photon billing show --json

Displays the active subscription for the current project, including plan details and status.

<Frame caption="A project on the free tier.">
<img src="/images/cli/billing/free.avif" alt="Terminal output of photon billing show for a project on the free tier" style={{ padding: "1rem" }} />
</Frame>

<Frame caption="A project on a paid plan.">
<img src="/images/cli/billing/paid.avif" alt="Terminal output of photon billing show for a project on a paid plan" style={{ padding: "1rem" }} />
</Frame>

## Start a checkout

```sh
Expand All @@ -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 <price-id>` to skip the picker.

<Frame caption="Starting a checkout from the interactive picker.">
<video src="/images/cli/billing/demo-billing.webm" autoPlay loop muted playsInline />
</Frame>

Available tiers: `pro`, `business`, `enterprise`.

| Flag | Description |
Expand Down
11 changes: 0 additions & 11 deletions cli/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
4 changes: 4 additions & 0 deletions cli/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,10 @@ photon spectrum lines ls
photon billing show
```

<Frame caption="A quick tour of the Photon CLI — listing projects, selecting one, and inspecting Spectrum and billing.">
<video src="/images/cli/overview/demo-overview.webm" autoPlay loop muted playsInline />
</Frame>

## Command tree

```text
Expand Down
10 changes: 7 additions & 3 deletions cli/profile-and-utilities.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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.

@coderabbitai coderabbitai Bot Jun 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Extract and compare whoami descriptions from both files
echo "=== profile-and-utilities.mdx (line 80) ==="
sed -n '80p' cli/profile-and-utilities.mdx

echo -e "\n=== authentication.mdx (line 36) ==="
sed -n '36p' cli/authentication.mdx

Repository: photon-hq/docs

Length of output: 400

Update whoami description to match active voice style in cli/authentication.mdx.

Line 80 currently reads: "Prints your name, email, and the backend you're signed in to. Returns an error with a login hint if your session has expired."

This conflicts with the cli/authentication.mdx documentation for the same command, which uses: "If the session has expired, you'll see a hint to re-run photon login."

Align line 80 to use active voice and second person, and include code formatting for the suggested action. Change "Returns an error with a login hint" to something like "you'll see a hint to re-run photon login" to follow the documentation guidelines consistently.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cli/profile-and-utilities.mdx` at line 80, The whoami command description
uses passive voice and is inconsistent with the style in cli/authentication.mdx.
Update the description to use active voice and second person perspective.
Replace the phrase "Returns an error with a login hint if your session has
expired" with "you'll see a hint to re-run `photon login`" and ensure the
command name is properly formatted with backticks to align with the
documentation guidelines used in cli/authentication.mdx.

Source: Coding guidelines


### auth status

Expand Down
30 changes: 26 additions & 4 deletions cli/projects.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@ photon projects ls --json

Aliases: `project ls`, `projects list`.

<Frame caption="Listing projects in the terminal.">
<img src="/images/cli/projects/projects-ls.avif" alt="Terminal output of photon projects ls showing a table of projects with id, name, location, status, platforms, and updated columns" style={{ padding: "1rem" }} />
</Frame>

## Show project details

```sh
Expand All @@ -23,23 +27,33 @@ photon projects show <project-id>

Defaults to `$PHOTON_PROJECT_ID` if no ID is given. Aliases: `projects get`.

<Frame caption="Viewing project details.">
<img src="/images/cli/projects/projects-show.avif" alt="Terminal output of photon projects show displaying a project's status, location, owner, timestamps, and other details" style={{ padding: "1rem" }} />
</Frame>

## Create a project

```sh
photon projects create
```

<Frame caption="Creating a project through the interactive wizard.">
<video src="/images/cli/projects/demo-create.webm" autoPlay loop muted playsInline />
</Frame>

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 <name>` | Project name |
| `--location <loc>` | Deployment region |
| `--spectrum` | Enable Spectrum for the project |
| `-n, --name <name>` | Project name |
| `-l, --location <location>` | Location (default: `United States`) |
| `--spectrum` / `--no-spectrum` | Enable / disable Spectrum |
| `--template` | Use the project as a template |
| `--observability` | Enable observability |

Aliases: `projects new`.

Expand Down Expand Up @@ -75,6 +89,10 @@ photon projects regenerate-secret -y

Generates a new Spectrum API secret for the project. The old secret stops working immediately.

<Frame caption="Rotating the Spectrum API secret.">
<video src="/images/cli/billing/demo-regenerate-secret.webm" autoPlay loop muted playsInline />
</Frame>

Aliases: `projects rotate-secret`.

## Open in the dashboard
Expand Down Expand Up @@ -112,6 +130,10 @@ photon projects upgrade --plan price_xxx

Available tiers: `pro`, `business`, `enterprise`.

<Frame caption="Upgrading a project from the interactive picker.">
<video src="/images/cli/billing/demo-upgrade.webm" autoPlay loop muted playsInline />
</Frame>

| Flag | Description |
|------|-------------|
| `[tier]` | Positional tier (`pro` / `business` / `enterprise`). Skips the picker. |
Expand Down
6 changes: 5 additions & 1 deletion cli/spectrum.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -66,6 +66,10 @@ photon spectrum lines ls

Aliases: `spectrum lines list`.

<Frame caption="Listing a project's Spectrum lines.">
<img src="/images/cli/spectrum/spectrum-lines.avif" alt="Terminal output of photon spectrum lines ls showing a table of phone lines with id, platform, number, and status columns" style={{ padding: "1rem" }} />
</Frame>

### Add a line

```sh
Expand Down
Binary file added images/cli/authentication/login-cli.avif
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/authentication/login-web.avif
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/authentication/whoami-cli.avif
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/billing/demo-billing.webm
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/billing/demo-regenerate-secret.webm
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/billing/demo-upgrade.webm
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/billing/free.avif
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/billing/paid.avif
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/overview/demo-overview.webm
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/projects/demo-create.webm
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/projects/projects-ls.avif
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/projects/projects-show.avif
View file
Open in desktop
Binary file not shown.
Binary file added images/cli/spectrum/spectrum-lines.avif
View file
Open in desktop
Binary file not shown.
Loading